docs(encoding): Cleanup and fix doc lints

_tools/check_docs.ts

@@ -30,6 +30,7 @@ const ENTRY_POINTS = [
   "../bytes/mod.ts",
   "../collections/mod.ts",
   "../datetime/mod.ts",
+  "../encoding/mod.ts",
   "../internal/mod.ts",
   "../jsonc/mod.ts",
   "../media_types/mod.ts",

encoding/ascii85.ts

@@ -51,11 +51,17 @@ const Z85 =
 /**
  * Converts data into an ascii58-encoded string.
  *
- * @example
+ * @param data The data to encode.
+ * @param options Options for encoding.
+ *
+ * @returns The ascii85-encoded string.
+ *
+ * @example Usage
  * ```ts
  * import { encodeAscii85 } from "@std/encoding/ascii85";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * encodeAscii85("Hello world!"); // "87cURD]j7BEbo80"
+ * assertEquals(encodeAscii85("Hello world!"), "87cURD]j7BEbo80");
  * ```
  */
 export function encodeAscii85(
@@ -130,12 +136,15 @@ export function encodeAscii85(
  * @param options Options for decoding.
  * @returns The decoded data.
  *
- * @example
+ * @example Usage
  * ```ts
  * import { decodeAscii85 } from "@std/encoding/ascii85";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * decodeAscii85("87cURD]j7BEbo80");
- * // Uint8Array(12) [ 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ]
+ * assertEquals(
+ *   decodeAscii85("87cURD]j7BEbo80"),
+ *   new TextEncoder().encode("Hello world!"),
+ * );
  * ```
  */
 export function decodeAscii85(

encoding/base32.ts

@@ -13,10 +13,14 @@
  *
  * ```ts
  * import { encodeBase32, decodeBase32 } from "@std/encoding/base32";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * const encoded = encodeBase32("foobar"); // "MZXW6YTBOI======"
+ * assertEquals(encodeBase32("foobar"), "MZXW6YTBOI======");
  *
- * decodeBase32(encoded); // Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ]
+ * assertEquals(
+ *   decodeBase32("MZXW6YTBOI======"),
+ *   new TextEncoder().encode("foobar")
+ * );
  * ```
  *
  * @module
@@ -64,12 +68,15 @@ function _byteLength(validLen: number, placeHoldersLen: number): number {
  * @param b32 The base32-encoded string to decode.
  * @returns The decoded data.
  *
- * @example
+ * @example Usage
  * ```ts
  * import { decodeBase32 } from "@std/encoding/base32";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * decodeBase32("NRQMA===");
- * // Uint8Array(3) [ 108, 96, 192 ]
+ * assertEquals(
+ *   decodeBase32("GZRTMMDDGA======"),
+ *   new TextEncoder().encode("6c60c0"),
+ * );
  * ```
  */
 export function decodeBase32(b32: string): Uint8Array {
@@ -170,11 +177,12 @@ function encodeChunk(uint8: Uint8Array, start: number, end: number): string {
  * @param data The data to encode.
  * @returns The base32-encoded string.
  *
- * @example
+ * @example Usage
  * ```ts
  * import { encodeBase32 } from "@std/encoding/base32";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * encodeBase32("6c60c0"); // "NRQMA==="
+ * assertEquals(encodeBase32("6c60c0"), "GZRTMMDDGA======");
  * ```
  */
 export function encodeBase32(data: ArrayBuffer | Uint8Array | string): string {

encoding/base58.ts

@@ -10,11 +10,13 @@
  *
  * ```ts
  * import { encodeBase58, decodeBase58 } from "@std/encoding/base58";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * const encoded = encodeBase58("Hello World!"); // "2NEpo7TZRRrLZSi2U"
+ * const hello = new TextEncoder().encode("Hello World!");
  *
- * decodeBase58(encoded);
- * // Uint8Array(12) [ 72, 101, 108, 108, 111, 32,  87, 111, 114, 108, 100, 33 ]
+ * assertEquals(encodeBase58(hello), "2NEpo7TZRRrLZSi2U");
+ *
+ * assertEquals(decodeBase58("2NEpo7TZRRrLZSi2U"), hello);
  * ```
  *
  * @module
@@ -43,11 +45,12 @@ const base58alphabet =
  * @param data The data to encode.
  * @returns The base58-encoded string.
  *
- * @example
+ * @example Usage
  * ```ts
  * import { encodeBase58 } from "@std/encoding/base58";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * encodeBase58("Hello World!"); // "2NEpo7TZRRrLZSi2U"
+ * assertEquals(encodeBase58("Hello World!"), "2NEpo7TZRRrLZSi2U");
  * ```
  */
 export function encodeBase58(data: ArrayBuffer | Uint8Array | string): string {
@@ -108,12 +111,15 @@ export function encodeBase58(data: ArrayBuffer | Uint8Array | string): string {
  * @param b58 The base58-encoded string to decode.
  * @returns The decoded data.
  *
- * @example
+ * @example Usage
  * ```ts
  * import { decodeBase58 } from "@std/encoding/base58";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * decodeBase58("2NEpo7TZRRrLZSi2U");
- * // Uint8Array(12) [ 72, 101, 108, 108, 111, 32,  87, 111, 114, 108, 100, 33 ]
+ * assertEquals(
+ *   decodeBase58("2NEpo7TZRRrLZSi2U"),
+ *   new TextEncoder().encode("Hello World!")
+ * );
  * ```
  */
 export function decodeBase58(b58: string): Uint8Array {

encoding/base64.ts

@@ -13,10 +13,12 @@
  *   encodeBase64,
  *   decodeBase64,
  * } from "@std/encoding/base64";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * const encoded = encodeBase64("foobar"); // "Zm9vYmFy"
+ * const foobar = new TextEncoder().encode("foobar");
  *
- * decodeBase64(encoded); // Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ]
+ * assertEquals(encodeBase64(foobar), "Zm9vYmFy");
+ * assertEquals(decodeBase64("Zm9vYmFy"), foobar);
  * ```
  *
  * @module
@@ -99,11 +101,12 @@ const base64abc = [
  * @param data The data to encode.
  * @returns The base64-encoded string.
  *
- * @example
+ * @example Usage
  * ```ts
  * import { encodeBase64 } from "@std/encoding/base64";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * encodeBase64("foobar"); // "Zm9vYmFy"
+ * assertEquals(encodeBase64("foobar"), "Zm9vYmFy");
  * ```
  */
 export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string {
@@ -151,11 +154,15 @@ export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string {
  * @param b64 The base64-encoded string to decode.
  * @returns The decoded data.
  *
- * @example
+ * @example Usage
  * ```ts
  * import { decodeBase64 } from "@std/encoding/base64";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * decodeBase64("Zm9vYmFy"); // Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ]
+ * assertEquals(
+ *   decodeBase64("Zm9vYmFy"),
+ *   new TextEncoder().encode("foobar")
+ * );
  * ```
  */
 export function decodeBase64(b64: string): Uint8Array {

encoding/base64url.ts

@@ -52,11 +52,12 @@ function convertBase64ToBase64url(b64: string) {
  * @param data The data to encode.
  * @returns The base64url-encoded string.
  *
- * @example
+ * @example Usage
  * ```ts
  * import { encodeBase64Url } from "@std/encoding/base64url";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * encodeBase64Url("foobar"); // "Zm9vYmFy"
+ * assertEquals(encodeBase64Url("foobar"), "Zm9vYmFy");
  * ```
  */
 export function encodeBase64Url(
@@ -73,11 +74,15 @@ export function encodeBase64Url(
  * @param b64url The base64url-encoded string to decode.
  * @returns The decoded data.
  *
- * @example
+ * @example Usage
  * ```ts
  * import { decodeBase64Url } from "@std/encoding/base64url";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * decodeBase64Url("Zm9vYmFy"); // Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ]
+ * assertEquals(
+ *   decodeBase64Url("Zm9vYmFy"),
+ *   new TextEncoder().encode("foobar")
+ * );
  * ```
  */
 export function decodeBase64Url(b64url: string): Uint8Array {

encoding/hex.ts

@@ -15,10 +15,14 @@
  *   decodeHex,
  *   encodeHex,
  * } from "@std/encoding/hex";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * const encoded = encodeHex("abc"); // "616263"
+ * assertEquals(encodeHex("abc"), "616263");
  *
- * decodeHex(encoded); // Uint8Array(3) [ 97, 98, 99 ]
+ * assertEquals(
+ *   decodeHex("616263"),
+ *   new TextEncoder().encode("abc"),
+ * );
  * ```
  *
  * @module
@@ -53,11 +57,16 @@ function fromHexChar(byte: number): number {
 /**
  * Converts data into a hex-encoded string.
  *
- * @example
+ * @param src The data to encode.
+ *
+ * @returns The hex-encoded string.
+ *
+ * @example Usage
  * ```ts
  * import { encodeHex } from "@std/encoding/hex";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * encodeHex("abc"); // "616263"
+ * assertEquals(encodeHex("abc"), "616263");
  * ```
  */
 export function encodeHex(src: string | Uint8Array | ArrayBuffer): string {
@@ -76,11 +85,19 @@ export function encodeHex(src: string | Uint8Array | ArrayBuffer): string {
  * Decodes the given hex-encoded string. If the input is malformed, an error is
  * thrown.
  *
- * @example
+ * @param src The hex-encoded string to decode.
+ *
+ * @returns The decoded data.
+ *
+ * @example Usage
  * ```ts
  * import { decodeHex } from "@std/encoding/hex";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * decodeHex("616263"); // Uint8Array(3) [ 97, 98, 99 ]
+ * assertEquals(
+ *   decodeHex("616263"),
+ *   new TextEncoder().encode("abc"),
+ * );
  * ```
  */
 export function decodeHex(src: string): Uint8Array {