docs(encoding): complete documentation

encoding/ascii85.ts

@@ -4,8 +4,7 @@
 import { validateBinaryLike } from "./_util.ts";
 
 /**
- * {@linkcode encode} and {@linkcode decode} for
- * [Ascii85/base85](https://en.wikipedia.org/wiki/Ascii85) encoding.
+ * Utilities for working with [ascii85]{@link https://en.wikipedia.org/wiki/Ascii85} encoding.
  *
  * This module is browser compatible.
  *
@@ -23,36 +22,25 @@ import { validateBinaryLike } from "./_util.ts";
  * encoded data for btoa. Checksums for btoa are not supported. Delimiters are not
  * supported by other encodings.)
  *
- * @example
- * ```ts
- * import {
- *   decodeAscii85,
- *   encodeAscii85,
- * } from "https://deno.land/std@$STD_VERSION/encoding/ascii85.ts";
- *
- * const a85Repr = "LpTqp";
- *
- * const binaryData = decodeAscii85(a85Repr);
- * console.log(binaryData);
- * // => Uint8Array [ 136, 180, 79, 24 ]
- *
- * console.log(encodeAscii85(binaryData));
- * // => LpTqp
- * ```
- *
  * @module
  */
 
+/** Supported ascii85 standards for {@linkcode Ascii85Options}. */
 export type Ascii85Standard = "Adobe" | "btoa" | "RFC 1924" | "Z85";
 
-/** encoding/decoding options */
+/** Options for {@linkcode encodeAscii85} and {@linkcode decodeAscii85}. */
 export interface Ascii85Options {
-  /** characterset and delimiter (if supported and used).
+  /**
+   * Character set and delimiter (if supported and used).
    *
    * @default {"Adobe"}
    */
   standard?: Ascii85Standard;
-  /** whether to use a delimiter (if supported) - "<~" and "~>" by default */
+  /**
+   * Whether to use a delimiter (if supported).
+   *
+   * @default {false}
+   */
   delimiter?: boolean;
 }
 const rfc1924 =
@@ -61,22 +49,25 @@ const Z85 =
   "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-:+=^!/*?&<>()[]{}@%$#";
 
 /**
- * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeAscii85} instead.
- *
  * Encodes a given Uint8Array into ascii85, supports multiple standards
  * @param uint8 input to encode
  * @param [options] encoding options
  * @param [options.standard=Adobe] encoding standard (Adobe, btoa, RFC 1924 or Z85)
  * @param [options.delimiter] whether to use a delimiter, if supported by encoding standard
+ *
+ * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeAscii85} instead.
  */
-export const encode = encodeAscii85;
+export const encode: typeof encodeAscii85 = encodeAscii85;
 
 /**
- * Encodes a given Uint8Array into ascii85, supports multiple standards
- * @param uint8 input to encode
- * @param [options] encoding options
- * @param [options.standard=Adobe] encoding standard (Adobe, btoa, RFC 1924 or Z85)
- * @param [options.delimiter] whether to use a delimiter, if supported by encoding standard
+ * Converts data into an ascii58-encoded string.
+ *
+ * @example
+ * ```ts
+ * import { encodeAscii85 } from "https://deno.land/std@$STD_VERSION/encoding/ascii85.ts";
+ *
+ * encodeAscii85("Hello world!"); // => "87cURD]j7BEbo80"
+ * ```
  */
 export function encodeAscii85(
   data: ArrayBuffer | Uint8Array | string,
@@ -144,20 +135,24 @@ export function encodeAscii85(
 }
 
 /**
- * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeAscii85} instead.
- *
  * Decodes a given ascii85 encoded string.
  * @param ascii85 input to decode
  * @param [options] decoding options
  * @param [options.standard=Adobe] encoding standard used in the input string (Adobe, btoa, RFC 1924 or Z85)
+ *
+ * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeAscii85} instead.
  */
-export const decode = decodeAscii85;
+export const decode: typeof decodeAscii85 = decodeAscii85;
 
 /**
- * Decodes a given ascii85 encoded string.
- * @param ascii85 input to decode
- * @param [options] decoding options
- * @param [options.standard=Adobe] encoding standard used in the input string (Adobe, btoa, RFC 1924 or Z85)
+ * Decodes a given ascii85-encoded string.
+ *
+ * @example
+ * ```ts
+ * import { decodeAscii85 } from "https://deno.land/std@$STD_VERSION/encoding/ascii85.ts";
+ *
+ * decodeAscii85("87cURD]j7BEbo80"); // => Uint8Array [ 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ]
+ * ```
  */
 export function decodeAscii85(
   ascii85: string,

encoding/base32.ts

@@ -5,30 +5,14 @@
 import { validateBinaryLike } from "./_util.ts";
 
 /**
- * {@linkcode encode} and {@linkcode decode} for
- * [base32](https://en.wikipedia.org/wiki/Base32) encoding.
+ * Utilities for
+ * [base32]{@link https://datatracker.ietf.org/doc/html/rfc4648#section-6}
+ * encoding and decoding.
  *
- * Modified from https://github.com/beatgammit/base64-js
+ * Modified from {@link https://github.com/beatgammit/base64-js}.
  *
  * This module is browser compatible.
  *
- * @example
- * ```ts
- * import {
- *   decodeBase32,
- *   encodeBase32,
- * } from "https://deno.land/std@$STD_VERSION/encoding/base32.ts";
- *
- * const b32Repr = "RC2E6GA=";
- *
- * const binaryData = decodeBase32(b32Repr);
- * console.log(binaryData);
- * // => Uint8Array [ 136, 180, 79, 24 ]
- *
- * console.log(encodeBase32(binaryData));
- * // => RC2E6GA=
- * ```
- *
  * @module
  */
 
@@ -80,16 +64,24 @@ function _byteLength(validLen: number, placeHoldersLen: number): number {
 }
 
 /**
- * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeBase32} instead.
- *
  * Decodes a given RFC4648 base32 encoded string.
  * @param b32
+ *
+ * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeBase32} instead.
  */
-export const decode = decodeBase32;
+export const decode: typeof decodeBase32 = decodeBase32;
 
 /**
- * Decodes a given RFC4648 base32 encoded string.
- * @param b32
+ * Decodes a base32-encoded string.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-6}
+ *
+ * @example
+ * ```ts
+ * import { decodeBase32 } from "https://deno.land/std@$STD_VERSION/encoding/base32.ts";
+ *
+ * decodeBase32("NRQMA==="); // Uint8Array(3) [ 108, 96, 192 ]
+ * ```
  */
 export function decodeBase32(b32: string): Uint8Array {
   let tmp: number;
@@ -182,15 +174,24 @@ function encodeChunk(uint8: Uint8Array, start: number, end: number): string {
 }
 
 /**
- * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeBase32} instead.
- *
  * Encodes a given Uint8Array into RFC4648 base32 representation
  * @param uint8
+ *
+ * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeBase32} instead.
  */
-export const encode = encodeBase32;
+export const encode: typeof encodeBase32 = encodeBase32;
 
 /**
- * Encodes a given Uint8Array into RFC4648 base32 representation
+ * Converts data to a base32-encoded string.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-6}
+ *
+ * @example
+ * ```ts
+ * import { encodeBase32 } from "https://deno.land/std@$STD_VERSION/encoding/base32.ts";
+ *
+ * encodeBase32("6c60c0"); // "NRQMA==="
+ * ```
  */
 export function encodeBase32(data: ArrayBuffer | Uint8Array | string): string {
   const uint8 = validateBinaryLike(data);

encoding/base58.ts

@@ -4,8 +4,9 @@
 import { validateBinaryLike } from "./_util.ts";
 
 /**
- * {@linkcode encodeBase58} and {@linkcode decodeBase58} for
- * [base58](https://en.wikipedia.org/wiki/Binary-to-text_encoding#Base58) encoding.
+ * Utilities for
+ * [base58]{@link https://datatracker.ietf.org/doc/html/draft-msporny-base58-03}
+ * encoding and decoding.
  *
  * This module is browser compatible.
  *
@@ -26,32 +27,32 @@ const base58alphabet =
   "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz".split("");
 
 /**
- * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeBase58} instead.
- *
  * Encodes a given Uint8Array, ArrayBuffer or string into draft-mspotny-base58-03 RFC base58 representation:
  * https://tools.ietf.org/id/draft-msporny-base58-01.html#rfc.section.1
  *
- * @param data
- *
- * @returns Encoded value
+ * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeBase58} instead.
  */
-export const encode = encodeBase58;
+export const encode: typeof encodeBase58 = encodeBase58;
 
 /**
- * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeBase58} instead.
- *
  * Decodes a given b58 string according to draft-mspotny-base58-03 RFC base58 representation:
  * https://tools.ietf.org/id/draft-msporny-base58-01.html#rfc.section.1
  *
- * @param b58
- *
- * @returns Decoded value
+ * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeBase58} instead.
  */
-export const decode = decodeBase58;
+export const decode: typeof decodeBase58 = decodeBase58;
 
 /**
- * Encodes a given Uint8Array, ArrayBuffer or string into draft-mspotny-base58-03 RFC base58 representation:
- * https://tools.ietf.org/id/draft-msporny-base58-01.html#rfc.section.1
+ * Converts data to a base58-encoded string.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/draft-msporny-base58-03#section-3}
+ *
+ * @example
+ * ```ts
+ * import { encodeBase58 } from "https://deno.land/std@$STD_VERSION/encoding/base58.ts";
+ *
+ * encodeBase58("Hello World!"); // "2NEpo7TZRRrLZSi2U"
+ * ```
  */
 export function encodeBase58(data: ArrayBuffer | Uint8Array | string): string {
   const uint8tData = validateBinaryLike(data);
@@ -102,8 +103,16 @@ export function encodeBase58(data: ArrayBuffer | Uint8Array | string): string {
 }
 
 /**
- * Decodes a given b58 string according to draft-mspotny-base58-03 RFC base58 representation:
- * https://tools.ietf.org/id/draft-msporny-base58-01.html#rfc.section.1
+ * Decodes a base58-encoded string.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/draft-msporny-base58-03#section-4}
+ *
+ * @example
+ * ```ts
+ * import { decodeBase58 } from "https://deno.land/std@$STD_VERSION/encoding/base58.ts";
+ *
+ * decodeBase58("2NEpo7TZRRrLZSi2U"); // Uint8Array(12) [ 72, 101, 108, 108, 111, 32,  87, 111, 114, 108, 100, 33 ]
+ * ```
  */
 export function decodeBase58(b58: string): Uint8Array {
   const splitInput = b58.trim().split("");

encoding/base64.ts

@@ -4,28 +4,12 @@
 import { validateBinaryLike } from "./_util.ts";
 
 /**
- * {@linkcode encodeBase64} and {@linkcode decodeBase64} for
- * [base64](https://en.wikipedia.org/wiki/Base64) encoding.
+ * Utilities for
+ * [base64]{@link https://datatracker.ietf.org/doc/html/rfc4648#section-4}
+ * encoding and decoding.
  *
  * This module is browser compatible.
  *
- * @example
- * ```ts
- * import {
- *   decodeBase64,
- *   encodeBase64,
- * } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts";
- *
- * const b64Repr = "Zm9vYg==";
- *
- * const binaryData = decodeBase64(b64Repr);
- * console.log(binaryData);
- * // => Uint8Array [ 102, 111, 111, 98 ]
- *
- * console.log(encodeBase64(binaryData));
- * // => Zm9vYg==
- * ```
- *
  * @module
  */
 
@@ -97,24 +81,31 @@ const base64abc = [
 ];
 
 /**
- * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeBase64} instead.
- *
  * CREDIT: https://gist.github.com/enepomnyaschih/72c423f727d395eeaa09697058238727
  * Encodes a given Uint8Array, ArrayBuffer or string into RFC4648 base64 representation
- * @param data
+ *
+ * @deprecated (will be removed in 0.210.0) Use {@linkcode encodeBase64} instead.
  */
-export const encode = encodeBase64;
+export const encode: typeof encodeBase64 = encodeBase64;
 
 /**
- * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeBase64} instead.
- *
  * Decodes a given RFC4648 base64 encoded string
- * @param b64
+ *
+ * @deprecated (will be removed in 0.210.0) Use {@linkcode decodeBase64} instead.
  */
-export const decode = decodeBase64;
+export const decode: typeof decodeBase64 = decodeBase64;
 
 /**
- * Encodes a given Uint8Array, ArrayBuffer or string into RFC4648 base64 representation
+ * Converts data into a base64-encoded string.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-4}
+ *
+ * @example
+ * ```ts
+ * import { encodeBase64 } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts";
+ *
+ * encodeBase64("foobar"); // "Zm9vYmFy"
+ * ```
  */
 export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string {
   // CREDIT: https://gist.github.com/enepomnyaschih/72c423f727d395eeaa09697058238727
@@ -145,7 +136,16 @@ export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string {
 }
 
 /**
- * Decodes a given RFC4648 base64 encoded string
+ * Decodes a base64-encoded string.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-4}
+ *
+ * @example
+ * ```ts
+ * import { encodeBase64 } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts";
+ *
+ * encodeBase64("foobar"); // "Zm9vYmFy"
+ * ```
  */
 export function decodeBase64(b64: string): Uint8Array {
   const binString = atob(b64);