docs(internal): cleanups and documentation improvements (#4706)

* feat(internal): `internal@1.0.0`

* work

* revert

* fix

* fix

_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/_types.ts

@@ -1,9 +0,0 @@
-// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
-
-export type DiffType = "removed" | "common" | "added";
-
-export interface DiffResult<T> {
-  type: DiffType;
-  value: T;
-  details?: DiffResult<T>[];
-}

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";

internal/styles.ts

@@ -5,53 +5,6 @@
 
 // This code is vendored from `fmt/colors.ts`.
 
-/**
- * String formatters and utilities for dealing with ANSI color codes.
- *
- * This module is browser compatible.
- *
- * This module supports `NO_COLOR` environmental variable disabling any coloring
- * if `NO_COLOR` is set.
- *
- * @example
- * ```ts
- * import {
- *   bgBlue,
- *   bgRgb24,
- *   bgRgb8,
- *   bold,
- *   italic,
- *   red,
- *   rgb24,
- *   rgb8,
- * } from "@std/fmt/colors";
- *
- * console.log(bgBlue(italic(red(bold("Hello, World!")))));
- *
- * // also supports 8bit colors
- *
- * console.log(rgb8("Hello, World!", 42));
- *
- * console.log(bgRgb8("Hello, World!", 42));
- *
- * // and 24bit rgb
- *
- * console.log(rgb24("Hello, World!", {
- *   r: 41,
- *   g: 42,
- *   b: 43,
- * }));
- *
- * console.log(bgRgb24("Hello, World!", {
- *   r: 41,
- *   g: 42,
- *   b: 43,
- * }));
- * ```
- *
- * @module
- */
-
 // deno-lint-ignore no-explicit-any
 const { Deno } = globalThis as any;
 const noColor = typeof Deno?.noColor === "boolean"
@@ -66,11 +19,6 @@ interface Code {
 
 const enabled = !noColor;
 
-/**
- * Builds color code
- * @param open
- * @param close
- */
 function code(open: number[], close: number): Code {
   return {
     open: `\x1b[${open.join(";")}m`,
@@ -79,11 +27,6 @@ function code(open: number[], close: number): Code {
   };
 }
 
-/**
- * Applies color and background based on color code and its associated text
- * @param str text to apply color settings to
- * @param code color code to apply
- */
 function run(str: string, code: Code): string {
   return enabled
     ? `${code.open}${str.replace(code.regexp, code.open)}${code.close}`
@@ -91,72 +34,170 @@ function run(str: string, code: Code): string {
 }
 
 /**
- * Make the text bold.
- * @param str text to make bold
+ * Sets the style of text to be printed to bold.
+ *
+ * Disable by setting the `NO_COLOR` environmental variable.
+ *
+ * @param str Text to make bold
+ *
+ * @returns Bold text for printing
+ *
+ * @example Usage
+ * ```ts
+ * import { bold } from "@std/internal/styles";
+ *
+ * console.log(bold("Hello, world!")); // Prints "Hello, world!" in bold
+ * ```
  */
 export function bold(str: string): string {
   return run(str, code([1], 22));
 }
 
 /**
- * Set text color to red.
- * @param str text to make red
+ * Sets the color of text to be printed to red.
+ *
+ * Disable by setting the `NO_COLOR` environmental variable.
+ *
+ * @param str Text to make red
+ *
+ * @returns Red text for printing
+ *
+ * @example Usage
+ * ```ts
+ * import { red } from "@std/internal/styles";
+ *
+ * console.log(red("Hello, world!")); // Prints "Hello, world!" in red
+ * ```
  */
 export function red(str: string): string {
   return run(str, code([31], 39));
 }
 
 /**
- * Set text color to green.
- * @param str text to make green
+ * Sets the color of text to be printed to green.
+ *
+ * Disable by setting the `NO_COLOR` environmental variable.
+ *
+ * @param str Text to make green
+ *
+ * @returns Green text for print
+ *
+ * @example Usage
+ * ```ts
+ * import { green } from "@std/internal/styles";
+ *
+ * console.log(green("Hello, world!")); // Prints "Hello, world!" in green
+ * ```
  */
 export function green(str: string): string {
   return run(str, code([32], 39));
 }
 
 /**
- * Set text color to yellow.
- * @param str text to make yellow
+ * Sets the color of text to be printed to yellow.
+ *
+ * Disable by setting the `NO_COLOR` environmental variable.
+ *
+ * @param str Text to make yellow
+ *
+ * @returns Yellow text for print
+ *
+ * @example Usage
+ * ```ts
+ * import { yellow } from "@std/internal/styles";
+ *
+ * console.log(yellow("Hello, world!")); // Prints "Hello, world!" in yellow
+ * ```
  */
 export function yellow(str: string): string {
   return run(str, code([33], 39));
 }
 
 /**
- * Set text color to white.
- * @param str text to make white
+ * Sets the color of text to be printed to white.
+ *
+ * @param str Text to make white
+ *
+ * @returns White text for print
+ *
+ * @example Usage
+ * ```ts
+ * import { white } from "@std/internal/styles";
+ *
+ * console.log(white("Hello, world!")); // Prints "Hello, world!" in white
+ * ```
  */
 export function white(str: string): string {
   return run(str, code([37], 39));
 }
 
 /**
- * Set text color to gray.
- * @param str text to make gray
+ * Sets the color of text to be printed to gray.
+ *
+ * @param str Text to make gray
+ *
+ * @returns Gray text for print
+ *
+ * @example Usage
+ * ```ts
+ * import { gray } from "@std/internal/styles";
+ *
+ * console.log(gray("Hello, world!")); // Prints "Hello, world!" in gray
+ * ```
  */
 export function gray(str: string): string {
   return brightBlack(str);
 }
 
 /**
- * Set text color to bright black.
- * @param str text to make bright-black
+ * Sets the color of text to be printed to bright-black.
+ *
+ * @param str Text to make bright-black
+ *
+ * @returns Bright-black text for print
+ *
+ * @example Usage
+ * ```ts
+ * import { brightBlack } from "@std/internal/styles";
+ *
+ * console.log(brightBlack("Hello, world!")); // Prints "Hello, world!" in bright-black
+ * ```
  */
-function brightBlack(str: string): string {
+export function brightBlack(str: string): string {
   return run(str, code([90], 39));
 }
 
 /**
- * Set background color to red.
- * @param str text to make its background red
+ * Sets the background color of text to be printed to red.
+ *
+ * @param str Text to make its background red
+ *
+ * @returns Red background text for print
+ *
+ * @example Usage
+ * ```ts
+ * import { bgRed } from "@std/internal/styles";
+ *
+ * console.log(bgRed("Hello, world!")); // Prints "Hello, world!" with red background
+ * ```
  */
 export function bgRed(str: string): string {
   return run(str, code([41], 49));
 }
 
 /**
- * Set background color to green.
- * @param str text to make its background green
+ * Sets the background color of text to be printed to green.
+ *
+ * @param str Text to make its background green
+ *
+ * @returns Green background text for print
+ *
+ * @example Usage
+ * ```ts
+ * import { bgGreen } from "@std/internal/styles";
+ *
+ * console.log(bgGreen("Hello, world!")); // Prints "Hello, world!" with green background
+ * ```
  */
 export function bgGreen(str: string): string {
   return run(str, code([42], 49));
@@ -174,7 +215,16 @@ const ANSI_PATTERN = new RegExp(
 /**
  * Remove ANSI escape codes from the string.
  *
- * @param string to remove ANSI escape codes from
+ * @param string Text to remove ANSI escape codes from
+ *
+ * @returns Text without ANSI escape codes
+ *
+ * @example Usage
+ * ```ts
+ * import { red, stripAnsiCode } from "@std/internal/styles";
+ *
+ * console.log(stripAnsiCode(red("Hello, world!"))); // Prints "Hello, world!"
+ * ```
  */
 export function stripAnsiCode(string: string): string {
   return string.replace(ANSI_PATTERN, "");

internal/types.ts

@@ -0,0 +1,18 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+
+/** Ways that lines in a diff can be different. */
+export type DiffType = "removed" | "common" | "added";
+
+/**
+ * Represents the result of a diff operation.
+ *
+ * @template T The type of the value in the diff result.
+ */
+export interface DiffResult<T> {
+  /** The type of the diff. */
+  type: DiffType;
+  /** The value of the diff. */
+  value: T;
+  /** The details of the diff. */
+  details?: DiffResult<T>[];
+}