docs(encoding): polish documentation (#4497)

deno.json

@@ -14,7 +14,7 @@
   },
   "tasks": {
     "test": "RUST_BACKTRACE=1 deno test --unstable-http --unstable-webgpu --doc --allow-all --parallel --coverage --trace-leaks",
-    "test:browser": "git grep --name-only \"This module is browser compatible.\" | grep -v deno.json | grep -v .github/workflows | grep -v _tools | xargs deno check --config browser-compat.tsconfig.json",
+    "test:browser": "git grep --name-only \"This module is browser compatible.\" | grep -v deno.json | grep -v .github/workflows | grep -v _tools | grep -v encoding/README.md | xargs deno check --config browser-compat.tsconfig.json",
     "fmt:licence-headers": "deno run --allow-read --allow-write ./_tools/check_licence.ts",
     "lint:deprecations": "deno run --allow-read --allow-net --allow-env=HOME ./_tools/check_deprecation.ts",
     "lint:doc-imports": "deno run --allow-env --allow-read ./_tools/check_doc_imports.ts",

encoding/README.md

@@ -0,0 +1,9 @@
+Utilities for encoding and decoding common formats like hex, base64, and varint.
+
+This module is browser compatible.
+
+```ts
+import { encodeBase64 } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts";
+
+encodeBase64("foobar"); // "Zm9vYmFy"
+```

encoding/ascii85.ts

@@ -55,7 +55,7 @@ const Z85 =
  * ```ts
  * import { encodeAscii85 } from "https://deno.land/std@$STD_VERSION/encoding/ascii85.ts";
  *
- * encodeAscii85("Hello world!"); // => "87cURD]j7BEbo80"
+ * encodeAscii85("Hello world!"); // "87cURD]j7BEbo80"
  * ```
  */
 export function encodeAscii85(
@@ -124,13 +124,18 @@ export function encodeAscii85(
 }
 
 /**
- * Decodes a given ascii85-encoded string.
+ * Decodes a ascii85-encoded string.
+ *
+ * @param ascii85 The ascii85-encoded string to decode.
+ * @param options Options for decoding.
+ * @returns The decoded data.
  *
  * @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 ]
+ * decodeAscii85("87cURD]j7BEbo80");
+ * // Uint8Array(12) [ 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ]
  * ```
  */
 export function decodeAscii85(
@@ -162,7 +167,7 @@ export function decodeAscii85(
       );
       break;
   }
-  //remove all invalid characters
+  // remove all invalid characters
   ascii85 = ascii85.replaceAll(/[^!-u]/g, "");
   const len = ascii85.length;
   const output = new Uint8Array(len + 4 - (len % 4));

encoding/base32.ts

@@ -11,6 +11,14 @@
  *
  * This module is browser compatible.
  *
+ * ```ts
+ * import { encodeBase32, decodeBase32 } from "https://deno.land/std@$STD_VERSION/encoding/base32.ts";
+ *
+ * const encoded = encodeBase32("foobar"); // "MZXW6YTBOI======"
+ *
+ * decodeBase32(encoded); // Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ]
+ * ```
+ *
  * @module
  */
 
@@ -53,11 +61,15 @@ function _byteLength(validLen: number, placeHoldersLen: number): number {
  *
  * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-6}
  *
+ * @param b32 The base32-encoded string to decode.
+ * @returns The decoded data.
+ *
  * @example
  * ```ts
  * import { decodeBase32 } from "https://deno.land/std@$STD_VERSION/encoding/base32.ts";
  *
- * decodeBase32("NRQMA==="); // Uint8Array(3) [ 108, 96, 192 ]
+ * decodeBase32("NRQMA===");
+ * // Uint8Array(3) [ 108, 96, 192 ]
  * ```
  */
 export function decodeBase32(b32: string): Uint8Array {
@@ -151,10 +163,13 @@ function encodeChunk(uint8: Uint8Array, start: number, end: number): string {
 }
 
 /**
- * Converts data to a base32-encoded string.
+ * Converts data into a base32-encoded string.
  *
  * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-6}
  *
+ * @param data The data to encode.
+ * @returns The base32-encoded string.
+ *
  * @example
  * ```ts
  * import { encodeBase32 } from "https://deno.land/std@$STD_VERSION/encoding/base32.ts";

encoding/base58.ts

@@ -8,6 +8,15 @@
  *
  * This module is browser compatible.
  *
+ * ```ts
+ * import { encodeBase58, decodeBase58 } from "https://deno.land/std@$STD_VERSION/encoding/base58.ts";
+ *
+ * const encoded = encodeBase58("Hello World!"); // "2NEpo7TZRRrLZSi2U"
+ *
+ * decodeBase58(encoded);
+ * // Uint8Array(12) [ 72, 101, 108, 108, 111, 32,  87, 111, 114, 108, 100, 33 ]
+ * ```
+ *
  * @module
  */
 
@@ -27,10 +36,13 @@ const base58alphabet =
   "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz".split("");
 
 /**
- * Converts data to a base58-encoded string.
+ * Converts data into a base58-encoded string.
  *
  * @see {@link https://datatracker.ietf.org/doc/html/draft-msporny-base58-03#section-3}
  *
+ * @param data The data to encode.
+ * @returns The base58-encoded string.
+ *
  * @example
  * ```ts
  * import { encodeBase58 } from "https://deno.land/std@$STD_VERSION/encoding/base58.ts";
@@ -93,11 +105,15 @@ export function encodeBase58(data: ArrayBuffer | Uint8Array | string): string {
  *
  * @see {@link https://datatracker.ietf.org/doc/html/draft-msporny-base58-03#section-4}
  *
+ * @param b58 The base58-encoded string to decode.
+ * @returns The decoded data.
+ *
  * @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 ]
+ * decodeBase58("2NEpo7TZRRrLZSi2U");
+ * // Uint8Array(12) [ 72, 101, 108, 108, 111, 32,  87, 111, 114, 108, 100, 33 ]
  * ```
  */
 export function decodeBase58(b58: string): Uint8Array {

encoding/base64.ts

@@ -8,6 +8,17 @@
  *
  * This module is browser compatible.
  *
+ * ```ts
+ * import {
+ *   encodeBase64,
+ *   decodeBase64,
+ * } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts";
+ *
+ * const encoded = encodeBase64("foobar"); // "Zm9vYmFy"
+ *
+ * decodeBase64(encoded); // Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ]
+ * ```
+ *
  * @module
  */
 
@@ -85,6 +96,9 @@ const base64abc = [
  *
  * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-4}
  *
+ * @param data The data to encode.
+ * @returns The base64-encoded string.
+ *
  * @example
  * ```ts
  * import { encodeBase64 } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts";
@@ -134,11 +148,14 @@ export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string {
  *
  * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-4}
  *
+ * @param b64 The base64-encoded string to decode.
+ * @returns The decoded data.
+ *
  * @example
  * ```ts
- * import { encodeBase64 } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts";
+ * import { decodeBase64 } from "https://deno.land/std@$STD_VERSION/encoding/base64.ts";
  *
- * encodeBase64("foobar"); // "Zm9vYmFy"
+ * decodeBase64("Zm9vYmFy"); // Uint8Array(6) [ 102, 111, 111, 98, 97, 114 ]
  * ```
  */
 export function decodeBase64(b64: string): Uint8Array {

encoding/base64url.ts

@@ -49,11 +49,14 @@ function convertBase64ToBase64url(b64: string) {
  *
  * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-5}
  *
+ * @param data The data to encode.
+ * @returns The base64url-encoded string.
+ *
  * @example
  * ```ts
  * import { encodeBase64Url } from "https://deno.land/std@$STD_VERSION/encoding/base64url.ts";
  *
- * encodeBase64Url(new TextEncoder().encode("foobar")); // "Zm9vYmFy"
+ * encodeBase64Url("foobar"); // "Zm9vYmFy"
  * ```
  */
 export function encodeBase64Url(
@@ -67,6 +70,9 @@ export function encodeBase64Url(
  *
  * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-5}
  *
+ * @param b64url The base64url-encoded string to decode.
+ * @returns The decoded data.
+ *
  * @example
  * ```ts
  * import { decodeBase64Url } from "https://deno.land/std@$STD_VERSION/encoding/base64url.ts";

encoding/hex.ts

@@ -10,20 +10,15 @@
  *
  * This module is browser compatible.
  *
- * @example
  * ```ts
  * import {
  *   decodeHex,
  *   encodeHex,
  * } from "https://deno.land/std@$STD_VERSION/encoding/hex.ts";
  *
- * const binary = new TextEncoder().encode("abc");
- * const encoded = encodeHex(binary);
- * console.log(encoded);
- * // => "616263"
+ * const encoded = encodeHex("abc"); // "616263"
  *
- * console.log(decodeHex(encoded));
- * // => Uint8Array(3) [ 97, 98, 99 ]
+ * decodeHex(encoded); // Uint8Array(3) [ 97, 98, 99 ]
  * ```
  *
  * @module

encoding/varint.ts

@@ -4,6 +4,16 @@
 /**
  * Functions for encoding typed integers in array buffers.
  *
+ * ```ts
+ * import { encode, decode } from "https://deno.land/std@$STD_VERSION/encoding/varint.ts";
+ *
+ * const buf = new Uint8Array(10);
+ * const [encoded, bytesWritten] = encode(42n, buf);
+ * // [ Uint8Array(1) [ 42 ], 1 ];
+ *
+ * decode(encoded); // [ 42n, 1 ];
+ * ```
+ *
  * @module
  */
 
@@ -37,6 +47,19 @@ const U64_VIEW = new BigUint64Array(AB);
  *
  * To know how many bytes the VarInt took to encode, simply negate `offset`
  * from the returned new `offset`.
+ *
+ * @param buf The buffer to decode from.
+ * @param offset The offset to start decoding from.
+ * @returns A tuple of the decoded varint 64-bit number, and the new offset.
+ *
+ * @example
+ * ```ts
+ * import { decode } from "https://deno.land/std@$STD_VERSION/encoding/varint.ts";
+ *
+ * const buf = new Uint8Array([0x8E, 0x02]);
+ * decode(buf);
+ * // [ 300n, 2 ];
+ * ```
  */
 export function decode(buf: Uint8Array, offset = 0): [bigint, number] {
   // Clear the last result from the Two's complement view
@@ -110,6 +133,19 @@ export function decode(buf: Uint8Array, offset = 0): [bigint, number] {
  *
  * To know how many bytes the VarInt took to encode, simply negate `offset`
  * from the returned new `offset`.
+ *
+ * @param buf The buffer to decode from.
+ * @param offset The offset to start decoding from.
+ * @returns A tuple of the decoded varint 32-bit number, and the new offset.
+ *
+ * @example
+ * ```ts
+ * import { decode32 } from "https://deno.land/std@$STD_VERSION/encoding/varint.ts";
+ *
+ * const buf = new Uint8Array([0x8E, 0x02]);
+ * decode32(buf);
+ * // [ 300, 2 ];
+ * ```
  */
 export function decode32(buf: Uint8Array, offset = 0): [number, number] {
   let shift = 0;
@@ -138,6 +174,19 @@ export function decode32(buf: Uint8Array, offset = 0): [number, number] {
  * If passed `buf` then that will be written into, starting at `offset`. The
  * resulting returned `Uint8Array` will be a slice of `buf`. The resulting
  * returned number is effectively `offset + bytesWritten`.
+ *
+ * @param num The number to encode.
+ * @param buf The buffer to write into.
+ * @param offset The offset to start writing at.
+ * @returns A tuple of the encoded VarInt `Uint8Array` and the new offset.
+ *
+ * @example
+ * ```ts
+ * import { encode } from "https://deno.land/std@$STD_VERSION/encoding/varint.ts";
+ *
+ * const buf = new Uint8Array(10);
+ * encode(42n, buf); // [ Uint8Array(1) [ 42 ], 1 ];
+ * ```
  */
 export function encode(
   num: bigint | number,