docs(assert): improve docs (#4876)

Co-authored-by: Asher Gomez <ashersaupingomez@gmail.com>

_tools/check_docs.ts

@@ -26,6 +26,7 @@ type DocNodeWithJsDoc<T = DocNodeBase> = T & {
 };
 
 const ENTRY_POINTS = [
+  "../assert/mod.ts",
   "../async/mod.ts",
   "../bytes/mod.ts",
   "../cli/mod.ts",

assert/assert.ts

@@ -5,13 +5,16 @@ import { AssertionError } from "./assertion_error.ts";
 /**
  * Make an assertion, error will be thrown if `expr` does not have truthy value.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assert } from "@std/assert/assert";
  *
  * assert("hello".includes("ello")); // Doesn't throw
  * assert("hello".includes("world")); // Throws
  * ```
+ *
+ * @param expr The expression to test.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assert(expr: unknown, msg = ""): asserts expr {
   if (!expr) {

assert/assert_almost_equals.ts

@@ -8,8 +8,8 @@ import { AssertionError } from "./assertion_error.ts";
  * double-precision floating-point representation limitations. If the values
  * are not almost equal then throw.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertAlmostEquals } from "@std/assert";
  *
  * assertAlmostEquals(0.01, 0.02, 0.1); // Doesn't throw
@@ -17,6 +17,11 @@ import { AssertionError } from "./assertion_error.ts";
  * assertAlmostEquals(0.1 + 0.2, 0.3, 1e-16); // Doesn't throw
  * assertAlmostEquals(0.1 + 0.2, 0.3, 1e-17); // Throws
  * ```
+ *
+ * @param actual The actual value to compare.
+ * @param expected The expected value to compare.
+ * @param tolerance The tolerance to consider the values almost equal. Defaults to 1e-7. (This will be changed in 1.0.0)
+ * @param msg The optional message to include in the error.
  */
 export function assertAlmostEquals(
   actual: number,

assert/assert_array_includes.ts

@@ -14,13 +14,18 @@ export type ArrayLikeArg<T> = ArrayLike<T> & object;
  * Type parameter can be specified to ensure values under comparison have the
  * same type.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertArrayIncludes } from "@std/assert/assert-array-includes";
  *
  * assertArrayIncludes([1, 2], [2]); // Doesn't throw
  * assertArrayIncludes([1, 2], [3]); // Throws
  * ```
+ *
+ * @typeParam T The type of the elements in the array to compare.
+ * @param actual The array-like object to check for.
+ * @param expected The array-like object to check for.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertArrayIncludes<T>(
   actual: ArrayLikeArg<T>,

assert/assert_equals.ts

@@ -4,6 +4,15 @@ import { equal } from "./equal.ts";
 import { buildMessage, diff, diffStr, format } from "@std/internal";
 import { AssertionError } from "./assertion_error.ts";
 
+/** Options for {@linkcode assertEquals}. */
+export type AssertEqualsOption = {
+  /** The option for formatting the values.
+   *
+   * Note: This option is experimental and may be removed in the future.
+   */
+  formatter?: (value: unknown) => string;
+};
+
 /**
  * Make an assertion that `actual` and `expected` are equal, deeply. If not
  * deeply equal, then throw.
@@ -11,8 +20,8 @@ import { AssertionError } from "./assertion_error.ts";
  * Type parameter can be specified to ensure values under comparison have the
  * same type.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertEquals } from "@std/assert/assert-equals";
  *
  * assertEquals("world", "world"); // Doesn't throw
@@ -20,12 +29,18 @@ import { AssertionError } from "./assertion_error.ts";
  * ```
  *
  * Note: formatter option is experimental and may be removed in the future.
+ *
+ * @typeParam T The type of the values to compare. This is usually inferred.
+ * @param actual The actual value to compare.
+ * @param expected The expected value to compare.
+ * @param msg The optional message to display if the assertion fails.
+ * @param options The optional object for the assertion.
  */
 export function assertEquals<T>(
   actual: T,
   expected: T,
   msg?: string,
-  options: { formatter?: (value: unknown) => string } = {},
+  options: AssertEqualsOption = {},
 ) {
   if (equal(actual, expected)) {
     return;

assert/assert_exists.ts

@@ -6,13 +6,17 @@ import { AssertionError } from "./assertion_error.ts";
  * Make an assertion that actual is not null or undefined.
  * If not then throw.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertExists } from "@std/assert/assert-exists";
  *
  * assertExists("something"); // Doesn't throw
  * assertExists(undefined); // Throws
  * ```
+ *
+ * @typeParam T The type of the actual value.
+ * @param actual The actual value to check.
+ * @param msg The optional message to include in the error if the assertion fails.
  */
 export function assertExists<T>(
   actual: T,

assert/assert_false.ts

@@ -8,13 +8,16 @@ export type Falsy = false | 0 | 0n | "" | null | undefined;
 /**
  * Make an assertion, error will be thrown if `expr` have truthy value.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertFalse } from "@std/assert/assert-false";
  *
  * assertFalse(false); // Doesn't throw
  * assertFalse(true); // Throws
  * ```
+ *
+ * @param expr The expression to test.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertFalse(expr: unknown, msg = ""): asserts expr is Falsy {
   if (expr) {

assert/assert_greater.ts

@@ -7,14 +7,19 @@ import { AssertionError } from "./assertion_error.ts";
  * Make an assertion that `actual` is greater than `expected`.
  * If not then throw.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertGreater } from "@std/assert/assert-greater";
  *
  * assertGreater(2, 1); // Doesn't throw
  * assertGreater(1, 1); // Throws
  * assertGreater(0, 1); // Throws
  * ```
+ *
+ * @typeParam T The type of the values to compare.
+ * @param actual The actual value to compare.
+ * @param expected The expected value to compare.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertGreater<T>(actual: T, expected: T, msg?: string) {
   if (actual > expected) return;

assert/assert_greater_or_equal.ts

@@ -7,14 +7,19 @@ import { AssertionError } from "./assertion_error.ts";
  * Make an assertion that `actual` is greater than or equal to `expected`.
  * If not then throw.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertGreaterOrEqual } from "@std/assert/assert-greater-or-equal";
  *
  * assertGreaterOrEqual(2, 1); // Doesn't throw
  * assertGreaterOrEqual(1, 1); // Doesn't throw
  * assertGreaterOrEqual(0, 1); // Throws
  * ```
+ *
+ * @typeParam T The type of the values to compare.
+ * @param actual The actual value to compare.
+ * @param expected The expected value to compare.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertGreaterOrEqual<T>(
   actual: T,

assert/assert_instance_of.ts

@@ -14,13 +14,18 @@ new (...args: any) => infer C ? C
  * Make an assertion that `obj` is an instance of `type`.
  * If not then throw.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertInstanceOf } from "@std/assert/assert-instance-of";
  *
  * assertInstanceOf(new Date(), Date); // Doesn't throw
  * assertInstanceOf(new Date(), Number); // Throws
  * ```
+ *
+ * @typeParam T The expected type of the object.
+ * @param actual The object to check.
+ * @param expectedType The expected class constructor.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertInstanceOf<T extends AnyConstructor>(
   actual: unknown,

assert/assert_is_error.ts

@@ -9,8 +9,8 @@ import { stripAnsiCode } from "@std/internal/styles";
  * An error class and a string that should be included in the
  * error message can also be asserted.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertIsError } from "@std/assert/assert-is-error";
  *
  * assertIsError(null); // Throws
@@ -19,6 +19,12 @@ import { stripAnsiCode } from "@std/internal/styles";
  * assertIsError(new RangeError("Out of range"), SyntaxError, "Out of range"); // Doesn't throw
  * assertIsError(new RangeError("Out of range"), SyntaxError, "Within range"); // Throws
  * ```
+ *
+ * @typeParam E The type of the error to assert.
+ * @param error The error to assert.
+ * @param ErrorClass The optional error class to assert.
+ * @param msgMatches The optional string or RegExp to assert in the error message.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertIsError<E extends Error = Error>(
   error: unknown,

assert/assert_less.ts

@@ -7,13 +7,18 @@ import { AssertionError } from "./assertion_error.ts";
  * Make an assertion that `actual` is less than `expected`.
  * If not then throw.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertLess } from "@std/assert/assert-less";
  *
  * assertLess(1, 2); // Doesn't throw
  * assertLess(2, 1); // Throws
  * ```
+ *
+ * @typeParam T The type of the values to compare.
+ * @param actual The actual value to compare.
+ * @param expected The expected value to compare.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertLess<T>(actual: T, expected: T, msg?: string) {
   if (actual < expected) return;

assert/assert_less_or_equal.ts

@@ -7,14 +7,19 @@ import { AssertionError } from "./assertion_error.ts";
  * Make an assertion that `actual` is less than or equal to `expected`.
  * If not then throw.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertLessOrEqual } from "@std/assert/assert-less-or-equal";
  *
  * assertLessOrEqual(1, 2); // Doesn't throw
  * assertLessOrEqual(1, 1); // Doesn't throw
  * assertLessOrEqual(1, 0); // Throws
  * ```
+ *
+ * @typeParam T The type of the values to compare.
+ * @param actual The actual value to compare.
+ * @param expected The expected value to compare.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertLessOrEqual<T>(
   actual: T,

assert/assert_match.ts

@@ -6,13 +6,17 @@ import { AssertionError } from "./assertion_error.ts";
  * Make an assertion that `actual` match RegExp `expected`. If not
  * then throw.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertMatch } from "@std/assert/assert-match";
  *
  * assertMatch("Raptor", RegExp(/Raptor/)); // Doesn't throw
  * assertMatch("Denosaurus", RegExp(/Raptor/)); // Throws
  * ```
+ *
+ * @param actual The actual value to be matched.
+ * @param expected The expected pattern to match.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertMatch(
   actual: string,

assert/assert_not_equals.ts

@@ -10,13 +10,18 @@ import { AssertionError } from "./assertion_error.ts";
  *
  * Type parameter can be specified to ensure values under comparison have the same type.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertNotEquals } from "@std/assert/assert-not-equals";
  *
  * assertNotEquals(1, 2); // Doesn't throw
  * assertNotEquals(1, 1); // Throws
  * ```
+ *
+ * @typeParam T The type of the values to compare.
+ * @param actual The actual value to compare.
+ * @param expected The expected value to compare.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertNotEquals<T>(actual: T, expected: T, msg?: string) {
   if (!equal(actual, expected)) {

assert/assert_not_instance_of.ts

@@ -6,13 +6,19 @@ import { assertFalse } from "./assert_false.ts";
  * Make an assertion that `obj` is not an instance of `type`.
  * If so, then throw.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertNotInstanceOf } from "@std/assert/assert-not-instance-of";
  *
  * assertNotInstanceOf(new Date(), Number); // Doesn't throw
  * assertNotInstanceOf(new Date(), Date); // Throws
  * ```
+ *
+ * @typeParam A The type of the object to check.
+ * @typeParam T The type of the class to check against.
+ * @param actual The object to check.
+ * @param unexpectedType The class constructor to check against.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertNotInstanceOf<A, T>(
   actual: A,

assert/assert_not_match.ts

@@ -6,13 +6,17 @@ import { AssertionError } from "./assertion_error.ts";
  * Make an assertion that `actual` not match RegExp `expected`. If match
  * then throw.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertNotMatch } from "@std/assert/assert-not-match";
  *
  * assertNotMatch("Denosaurus", RegExp(/Raptor/)); // Doesn't throw
  * assertNotMatch("Raptor", RegExp(/Raptor/)); // Throws
  * ```
+ *
+ * @param actual The actual value to match.
+ * @param expected The expected value to not match.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertNotMatch(
   actual: string,

assert/assert_not_strict_equals.ts

@@ -7,13 +7,18 @@ import { format } from "@std/internal/format";
  * Make an assertion that `actual` and `expected` are not strictly equal.
  * If the values are strictly equal then throw.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertNotStrictEquals } from "@std/assert/assert-not-strict-equals";
  *
  * assertNotStrictEquals(1, 1); // Doesn't throw
  * assertNotStrictEquals(1, 2); // Throws
  * ```
+ *
+ * @typeParam T The type of the values to compare.
+ * @param actual The actual value to compare.
+ * @param expected The expected value to compare.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertNotStrictEquals<T>(
   actual: T,

assert/assert_object_match.ts

@@ -6,13 +6,17 @@ import { assertEquals } from "./assert_equals.ts";
  * Make an assertion that `actual` object is a subset of `expected` object,
  * deeply. If not, then throw.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertObjectMatch } from "@std/assert/assert-object-match";
  *
  * assertObjectMatch({ foo: "bar" }, { foo: "bar" }); // Doesn't throw
  * assertObjectMatch({ foo: "bar" }, { foo: "baz" }); // Throws
  * ```
+ *
+ * @param actual The actual value to be matched.
+ * @param expected The expected value to match.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertObjectMatch(
   // deno-lint-ignore no-explicit-any

assert/assert_rejects.ts

@@ -8,13 +8,17 @@ import { assertIsError } from "./assert_is_error.ts";
  *
  * To assert that a synchronous function throws, use {@linkcode assertThrows}.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertRejects } from "@std/assert/assert-rejects";
  *
  * await assertRejects(async () => Promise.reject(new Error())); // Doesn't throw
  * await assertRejects(async () => console.log("Hello world")); // Throws
  * ```
+ *
+ * @param fn The function to execute.
+ * @param msg The optional message to display if the assertion fails.
+ * @returns The promise which resolves to the thrown error.
  */
 export function assertRejects(
   fn: () => PromiseLike<unknown>,
@@ -27,13 +31,20 @@ export function assertRejects(
  *
  * To assert that a synchronous function throws, use {@linkcode assertThrows}.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertRejects } from "@std/assert/assert-rejects";
  *
  * await assertRejects(async () => Promise.reject(new Error()), Error); // Doesn't throw
  * await assertRejects(async () => Promise.reject(new Error()), SyntaxError); // Throws
  * ```
+ *
+ * @typeParam E The error class to assert.
+ * @param fn The function to execute.
+ * @param ErrorClass The error class to assert.
+ * @param msgIncludes The string that should be included in the error message.
+ * @param msg The optional message to display if the assertion fails.
+ * @returns The promise which resolves to the thrown error.
  */
 export function assertRejects<E extends Error = Error>(
   fn: () => PromiseLike<unknown>,

assert/assert_strict_equals.ts

@@ -7,8 +7,8 @@ import { AssertionError } from "./assertion_error.ts";
  * Make an assertion that `actual` and `expected` are equal using
  * {@linkcode Object.is} for equality comparison. If not, then throw.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertStrictEquals } from "@std/assert/assert-strict-equals";
  *
  * const a = {};
@@ -19,6 +19,11 @@ import { AssertionError } from "./assertion_error.ts";
  * const d = {};
  * assertStrictEquals(c, d); // Throws
  * ```
+ *
+ * @typeParam T The type of the expected value.
+ * @param actual The actual value to compare.
+ * @param expected The expected value to compare.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertStrictEquals<T>(
   actual: unknown,

assert/assert_string_includes.ts

@@ -6,13 +6,17 @@ import { AssertionError } from "./assertion_error.ts";
  * Make an assertion that actual includes expected. If not
  * then throw.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertStringIncludes } from "@std/assert/assert-string-includes";
  *
  * assertStringIncludes("Hello", "ello"); // Doesn't throw
  * assertStringIncludes("Hello", "world"); // Throws
  * ```
+ *
+ * @param actual The actual string to check for inclusion.
+ * @param expected The expected string to check for inclusion.
+ * @param msg The optional message to display if the assertion fails.
  */
 export function assertStringIncludes(
   actual: string,

assert/assert_throws.ts

@@ -10,13 +10,17 @@ import { AssertionError } from "./assertion_error.ts";
  * To assert that an asynchronous function rejects, use
  * {@linkcode assertRejects}.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertThrows } from "@std/assert/assert-throws";
  *
  * assertThrows(() => { throw new TypeError("hello world!"); }); // Doesn't throw
  * assertThrows(() => console.log("hello world!")); // Throws
  * ```
+ *
+ * @param fn The function to execute.
+ * @param msg The optional message to display if the assertion fails.
+ * @returns The error that was thrown.
  */
 export function assertThrows(
   fn: () => unknown,
@@ -30,13 +34,20 @@ export function assertThrows(
  * To assert that an asynchronous function rejects, use
  * {@linkcode assertRejects}.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { assertThrows } from "@std/assert/assert-throws";
  *
  * assertThrows(() => { throw new TypeError("hello world!"); }, TypeError); // Doesn't throw
  * assertThrows(() => { throw new TypeError("hello world!"); }, RangeError); // Throws
  * ```
+ *
+ * @typeParam E The error class to assert.
+ * @param fn The function to execute.
+ * @param ErrorClass The error class to assert.
+ * @param msgIncludes The string that should be included in the error message.
+ * @param msg The optional message to display if the assertion fails.
+ * @returns The error that was thrown.
  */
 export function assertThrows<E extends Error = Error>(
   fn: () => unknown,

assert/assertion_error.ts

@@ -4,15 +4,25 @@
 /**
  * Error thrown when an assertion fails.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { AssertionError } from "@std/assert/assertion-error";
  *
  * throw new AssertionError("Assertion failed");
  * ```
  */
 export class AssertionError extends Error {
-  /** Constructs a new instance. */
+  /** Constructs a new instance.
+   *
+   * @example Usage
+   * ```ts no-eval
+   * import { AssertionError } from "@std/assert/assertion-error";
+   *
+   * throw new AssertionError("Assertion failed");
+   * ```
+   *
+   * @param message The error message.
+   */
   constructor(message: string) {
     super(message);
     this.name = "AssertionError";

assert/equal.ts

@@ -12,10 +12,12 @@ function constructorsEqual(a: object, b: object) {
 
 /**
  * Deep equality comparison used in assertions
- * @param c actual value
- * @param d expected value
  *
- * @example
+ * @param c The actual value
+ * @param d The expected value
+ * @returns `true` if the values are deeply equal, `false` otherwise
+ *
+ * @example Usage
  * ```ts
  * import { equal } from "@std/assert/equal";
  *

assert/fail.ts

@@ -5,12 +5,15 @@ import { assert } from "./assert.ts";
 /**
  * Forcefully throws a failed assertion.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { fail } from "@std/assert/fail";
  *
  * fail("Deliberately failed!"); // Throws
  * ```
+ *
+ * @param msg Optional message to include in the error.
+ * @returns Never returns, always throws.
  */
 export function fail(msg?: string): never {
   const msgSuffix = msg ? `: ${msg}` : ".";

assert/unimplemented.ts

@@ -5,12 +5,15 @@ import { AssertionError } from "./assertion_error.ts";
 /**
  * Use this to stub out methods that will throw when invoked.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { unimplemented } from "@std/assert/unimplemented";
  *
  * unimplemented(); // Throws
  * ```
+ *
+ * @param msg Optional message to include in the error.
+ * @returns Never returns, always throws.
  */
 export function unimplemented(msg?: string): never {
   const msgSuffix = msg ? `: ${msg}` : ".";

assert/unreachable.ts

@@ -5,12 +5,15 @@ import { AssertionError } from "./assertion_error.ts";
 /**
  * Use this to assert unreachable code.
  *
- * @example
- * ```ts
+ * @example Usage
+ * ```ts no-eval
  * import { unreachable } from "@std/assert/unreachable";
  *
  * unreachable(); // Throws
  * ```
+ *
+ * @param reason The reason why the code should be unreachable.
+ * @returns Never returns, always throws.
  */
 export function unreachable(reason?: string): never {
   throw new AssertionError(reason ?? "unreachable");