chore: Add doc comments for most methods, deprecate some methods

src/encode.ts

@@ -3,14 +3,38 @@ import xmlMap from "./maps/xml.json";
 const inverseXML = getInverseObj(xmlMap);
 const xmlReplacer = getInverseReplacer(inverseXML);
 
-export const encodeXML = getInverse(inverseXML, xmlReplacer);
+/**
+ * Encodes all non-ASCII characters, as well as characters not valid in XML
+ * documents using XML entities.
+ *
+ * If a character has no equivalent entity, a
+ * numeric hexadecimal reference (eg. `ü`) will be used.
+ */
+export const encodeXML = getASCIIEncoder(inverseXML);
 
 import htmlMap from "./maps/entities.json";
 
 const inverseHTML = getInverseObj(htmlMap);
 const htmlReplacer = getInverseReplacer(inverseHTML);
 
+/**
+ * Encodes all entities and non-ASCII characters in the input.
+ *
+ * This includes characters that are valid ASCII characters in HTML documents.
+ * For example `#` will be encoded as `#`. To get a more compact output,
+ * consider using the `encodeNonAsciiHTML` function.
+ *
+ * If a character has no equivalent entity, a
+ * numeric hexadecimal reference (eg. `ü`) will be used.
+ */
 export const encodeHTML = getInverse(inverseHTML, htmlReplacer);
+/**
+ * Encodes all non-ASCII characters, as well as characters not valid in HTML
+ * documents using HTML entities.
+ *
+ * If a character has no equivalent entity, a
+ * numeric hexadecimal reference (eg. `ü`) will be used.
+ */
 export const encodeNonAsciiHTML = getASCIIEncoder(inverseHTML);
 
 import { MapType } from "./decode";
@@ -63,6 +87,7 @@ function getInverseReplacer(inverse: MapType): RegExp {
     return new RegExp(multiple.join("|"), "g");
 }
 
+// /[^\0-\x7F]/gu
 const reNonASCII = /(?:[\x80-\uD7FF\uE000-\uFFFF]|[\uD800-\uDBFF][\uDC00-\uDFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?:[^\uD800-\uDBFF]|^)[\uDC00-\uDFFF])/g;
 
 const getCodePoint =
@@ -94,6 +119,15 @@ const reEscapeChars = new RegExp(
     "g"
 );
 
+/**
+ * Encodes all non-ASCII characters, as well as characters not valid in XML
+ * documents using numeric hexadecimal reference (eg. `ü`).
+ *
+ * Have a look at `escapeUTF8` if you want a more concise output at the expense
+ * of reduced transportability.
+ *
+ * @param data String to escape.
+ */
 export function escape(data: string): string {
     return data.replace(reEscapeChars, singleCharReplacer);
 }

src/index.ts

@@ -6,6 +6,7 @@ import { encodeXML, encodeHTML } from "./encode";
  *
  * @param data String to decode.
  * @param level Optional level to decode at. 0 = XML, 1 = HTML. Default is 0.
+ * @deprecated Use `decodeXML` or `decodeHTML` directly.
  */
 export function decode(data: string, level?: number): string {
     return (!level || level <= 0 ? decodeXML : decodeHTML)(data);
@@ -16,6 +17,7 @@ export function decode(data: string, level?: number): string {
  *
  * @param data String to decode.
  * @param level Optional level to decode at. 0 = XML, 1 = HTML. Default is 0.
+ * @deprecated Use `decodeHTMLStrict` or `decodeXML` directly.
  */
 export function decodeStrict(data: string, level?: number): string {
     return (!level || level <= 0 ? decodeXML : decodeHTMLStrict)(data);
@@ -26,6 +28,7 @@ export function decodeStrict(data: string, level?: number): string {
  *
  * @param data String to encode.
  * @param level Optional level to encode at. 0 = XML, 1 = HTML. Default is 0.
+ * @deprecated Use `encodeHTML`, `encodeXML` or `encodeNonAsciiHTML` directly.
  */
 export function encode(data: string, level?: number): string {
     return (!level || level <= 0 ? encodeXML : encodeHTML)(data);
@@ -36,8 +39,8 @@ export {
     encodeHTML,
     encodeNonAsciiHTML,
     escape,
-    // Legacy aliases
     escapeUTF8,
+    // Legacy aliases (deprecated)
     encodeHTML as encodeHTML4,
     encodeHTML as encodeHTML5,
 } from "./encode";
@@ -46,7 +49,7 @@ export {
     decodeXML,
     decodeHTML,
     decodeHTMLStrict,
-    // Legacy aliases
+    // Legacy aliases (deprecated)
     decodeHTML as decodeHTML4,
     decodeHTML as decodeHTML5,
     decodeHTMLStrict as decodeHTML4Strict,