docs(internal): cleanups and documentation improvements

_tools/check_docs.ts

@@ -21,6 +21,7 @@ const ENTRY_POINTS = [
   "../bytes/mod.ts",
   "../datetime/mod.ts",
   "../collections/mod.ts",
+  "../internal/mod.ts",
   "../media_types/mod.ts",
 ] as const;
 

deno.json

@@ -19,7 +19,7 @@
     "lint:circular": "deno run --allow-env --allow-read --allow-net=deno.land,jsr.io ./_tools/check_circular_package_dependencies.ts",
     "lint:mod-exports": "deno run --allow-env --allow-read ./_tools/check_mod_exports.ts",
     "lint:tools-types": "deno check _tools/*.ts",
-    "lint:docs": "deno run -A _tools/check_docs.ts && deno doc --lint collections/mod.ts bytes/mod.ts datetime/mod.ts media_types/mod.ts url/mod.ts",
+    "lint:docs": "deno run -A _tools/check_docs.ts && deno doc --lint collections/mod.ts bytes/mod.ts datetime/mod.ts internal/mod.ts media_types/mod.ts url/mod.ts",
     "lint": "deno lint && deno task fmt:licence-headers --check && deno task lint:circular && deno task lint:deprecations && deno task lint:tools-types && deno task lint:mod-exports && deno task lint:docs",
     "typos": "typos -c ./.github/workflows/typos.toml",
     "build:crypto": "deno task --cwd crypto/_wasm wasmbuild",

internal/build_message.ts

@@ -2,7 +2,7 @@
 // This module is browser compatible.
 
 import { bgGreen, bgRed, bold, gray, green, red, white } from "./styles.ts";
-import type { DiffResult, DiffType } from "./_types.ts";
+import type { DiffResult, DiffType } from "./types.ts";
 
 /**
  * Colors the output of assertion diffs.
@@ -49,19 +49,48 @@ function createSign(diffType: DiffType): string {
   }
 }
 
+/** Options for {@linkcode buildMessage}. */
+export interface BuildMessageOptions {
+  /**
+   * Whether to output the diff as a single string.
+   *
+   * @default {false}
+   */
+  stringDiff?: boolean;
+}
+
 /**
  * Builds a message based on the provided diff result.
  *
  * @param diffResult The diff result array.
  * @param options Optional parameters for customizing the message.
- * @param options.stringDiff Whether to output the diff as a single string.
  *
  * @returns An array of strings representing the built message.
+ *
+ * @example Usage
+ * ```ts
+ * import { diffstr, buildMessage } from "@std/internal";
+ *
+ * const diffResult = diffstr("Hello, world!", "Hello, world");
+ *
+ * console.log(buildMessage(diffResult));
+ * // [
+ * //   "",
+ * //   "",
+ * //   "    [Diff] Actual / Expected",
+ * //   "",
+ * //   "",
+ * //   "-   Hello, world!",
+ * //   "+   Hello, world",
+ * //   "",
+ * // ]
+ * ```
  */
 export function buildMessage(
   diffResult: ReadonlyArray<DiffResult<string>>,
-  { stringDiff = false } = {},
+  options: BuildMessageOptions = {},
 ): string[] {
+  const { stringDiff = false } = options;
   const messages = [
     "",
     "",

internal/deno.json

@@ -7,6 +7,7 @@
     "./diff-str": "./diff_str.ts",
     "./diff": "./diff.ts",
     "./format": "./format.ts",
-    "./styles": "./styles.ts"
+    "./styles": "./styles.ts",
+    "./types": "./types.ts"
   }
 }

internal/diff.ts

@@ -1,7 +1,7 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-import type { DiffResult, DiffType } from "./_types.ts";
+import type { DiffResult, DiffType } from "./types.ts";
 
 interface FarthestPoint {
   y: number;
@@ -128,6 +128,22 @@ function createFp(
  * @param B Expected value
  *
  * @returns An array of differences between the actual and expected values.
+ *
+ * @example Usage
+ * ```ts
+ * import { diff } from "@std/internal/diff";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * const a = [1, 2, 3];
+ * const b = [1, 2, 4];
+ *
+ * assertEquals(diff(a, b), [
+ *   { type: "common", value: 1 },
+ *   { type: "common", value: 2 },
+ *   { type: "removed", value: 3 },
+ *   { type: "added", value: 4 },
+ * ]);
+ * ```
  */
 export function diff<T>(A: T[], B: T[]): DiffResult<T>[] {
   const prefixCommon = createCommon(A, B);

internal/diff_str.ts

@@ -1,5 +1,5 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
-import type { DiffResult } from "./_types.ts";
+import type { DiffResult } from "./types.ts";
 import { diff } from "./diff.ts";
 
 /**
@@ -106,6 +106,32 @@ function createDetails(
  * @param B Expected string
  *
  * @returns Array of diff results.
+ *
+ * @example Usage
+ * ```ts
+ * import { diffstr } from "@std/internal/diff-str";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * assertEquals(diffstr("Hello!", "Hello"), [
+ *   {
+ *     type: "removed",
+ *     value: "Hello!\n",
+ *     details: [
+ *       { type: "common", value: "Hello" },
+ *       { type: "removed", value: "!" },
+ *       { type: "common", value: "\n" }
+ *     ]
+ *   },
+ *   {
+ *     type: "added",
+ *     value: "Hello\n",
+ *     details: [
+ *       { type: "common", value: "Hello" },
+ *       { type: "common", value: "\n" }
+ *     ]
+ *   }
+ * ]);
+ * ```
  */
 export function diffstr(A: string, B: string): DiffResult<string>[] {
   // Compute multi-line diff

internal/format.ts

@@ -3,8 +3,21 @@
 
 /**
  * Converts the input into a string. Objects, Sets and Maps are sorted so as to
- * make tests less flaky
+ * make tests less flaky.
+ *
  * @param v Value to be formatted
+ *
+ * @returns The formatted string
+ *
+ * @example Usage
+ * ```ts
+ * import { format } from "@std/internal/format";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * assertEquals(format({ a: 1, b: 2 }), "{\n  a: 1,\n  b: 2,\n}");
+ * assertEquals(format(new Set([1, 2])), "Set(2) {\n  1,\n  2,\n}");
+ * assertEquals(format(new Map([[1, 2]])), "Map(1) {\n  1 => 2,\n}");
+ * ```
  */
 export function format(v: unknown): string {
   // deno-lint-ignore no-explicit-any

internal/mod.ts

@@ -12,3 +12,4 @@ export * from "./diff.ts";
 export * from "./diff_str.ts";
 export * from "./format.ts";
 export * from "./styles.ts";
+export * from "./types.ts";