docs(assert): improve docs

_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,15 +8,20 @@ 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
  * assertAlmostEquals(0.01, 0.02); // Throws
  * 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,28 +4,43 @@ 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.
  *
  * 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
  * assertEquals("hello", "world"); // Throws
  * ```
  *
  * 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,