From 386172dbd4fe0dfc33a88eb1d8dafc286bfb56aa Mon Sep 17 00:00:00 2001 From: Yoshiya Hinosawa Date: Wed, 29 May 2024 14:59:18 +0900 Subject: [PATCH 1/2] docs(assert): improve docs --- _tools/check_docs.ts | 1 + assert/assert.ts | 7 +++++-- assert/assert_almost_equals.ts | 9 +++++++-- assert/assert_array_includes.ts | 9 +++++++-- assert/assert_equals.ts | 21 ++++++++++++++++++--- assert/assert_exists.ts | 8 ++++++-- assert/assert_false.ts | 7 +++++-- assert/assert_greater.ts | 9 +++++++-- assert/assert_greater_or_equal.ts | 9 +++++++-- assert/assert_instance_of.ts | 9 +++++++-- assert/assert_is_error.ts | 10 ++++++++-- assert/assert_less.ts | 9 +++++++-- assert/assert_less_or_equal.ts | 9 +++++++-- assert/assert_match.ts | 8 ++++++-- assert/assert_not_equals.ts | 9 +++++++-- assert/assert_not_instance_of.ts | 10 ++++++++-- assert/assert_not_match.ts | 8 ++++++-- assert/assert_not_strict_equals.ts | 9 +++++++-- assert/assert_object_match.ts | 8 ++++++-- assert/assert_rejects.ts | 19 +++++++++++++++---- assert/assert_strict_equals.ts | 9 +++++++-- assert/assert_string_includes.ts | 8 ++++++-- assert/assert_throws.ts | 19 +++++++++++++++---- assert/assertion_error.ts | 16 +++++++++++++--- assert/equal.ts | 8 +++++--- assert/fail.ts | 7 +++++-- assert/unimplemented.ts | 7 +++++-- assert/unreachable.ts | 7 +++++-- 28 files changed, 208 insertions(+), 61 deletions(-) diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index 30b95f4476df..ab21fd733d89 100644 --- a/_tools/check_docs.ts +++ b/_tools/check_docs.ts @@ -26,6 +26,7 @@ type DocNodeWithJsDoc = T & { }; const ENTRY_POINTS = [ + "../assert/mod.ts", "../async/mod.ts", "../bytes/mod.ts", "../cli/mod.ts", diff --git a/assert/assert.ts b/assert/assert.ts index 8de6fe68a47b..fb1cc7b9c3a7 100644 --- a/assert/assert.ts +++ b/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) { diff --git a/assert/assert_almost_equals.ts b/assert/assert_almost_equals.ts index 55dc48401c2d..8a14fcf9c98a 100644 --- a/assert/assert_almost_equals.ts +++ b/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, diff --git a/assert/assert_array_includes.ts b/assert/assert_array_includes.ts index cc99c4f97e80..d7f007ecfb3b 100644 --- a/assert/assert_array_includes.ts +++ b/assert/assert_array_includes.ts @@ -14,13 +14,18 @@ export type ArrayLikeArg = ArrayLike & 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( actual: ArrayLikeArg, diff --git a/assert/assert_equals.ts b/assert/assert_equals.ts index e68ab693a242..0677f383cccb 100644 --- a/assert/assert_equals.ts +++ b/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"; +/** The option object 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( actual: T, expected: T, msg?: string, - options: { formatter?: (value: unknown) => string } = {}, + options: AssertEqualsOption = {}, ) { if (equal(actual, expected)) { return; diff --git a/assert/assert_exists.ts b/assert/assert_exists.ts index 78ee8aa1066b..0c8e886d3cca 100644 --- a/assert/assert_exists.ts +++ b/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( actual: T, diff --git a/assert/assert_false.ts b/assert/assert_false.ts index 953c63a7e36b..63546f74d57b 100644 --- a/assert/assert_false.ts +++ b/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) { diff --git a/assert/assert_greater.ts b/assert/assert_greater.ts index fb68c1cb4c69..6f289aec6dfa 100644 --- a/assert/assert_greater.ts +++ b/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(actual: T, expected: T, msg?: string) { if (actual > expected) return; diff --git a/assert/assert_greater_or_equal.ts b/assert/assert_greater_or_equal.ts index 6fb1d3fd67e2..258b92ed0a90 100644 --- a/assert/assert_greater_or_equal.ts +++ b/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( actual: T, diff --git a/assert/assert_instance_of.ts b/assert/assert_instance_of.ts index 75b7b1205b59..2f15a733b1b3 100644 --- a/assert/assert_instance_of.ts +++ b/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( actual: unknown, diff --git a/assert/assert_is_error.ts b/assert/assert_is_error.ts index 1c3331c66ca4..19ced6f2a2a7 100644 --- a/assert/assert_is_error.ts +++ b/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( error: unknown, diff --git a/assert/assert_less.ts b/assert/assert_less.ts index 8a4655fb3640..dfd265e98de8 100644 --- a/assert/assert_less.ts +++ b/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(actual: T, expected: T, msg?: string) { if (actual < expected) return; diff --git a/assert/assert_less_or_equal.ts b/assert/assert_less_or_equal.ts index 4e3c93b49521..a4a9c0933cf5 100644 --- a/assert/assert_less_or_equal.ts +++ b/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( actual: T, diff --git a/assert/assert_match.ts b/assert/assert_match.ts index 2f18b84b9816..5bdf86895157 100644 --- a/assert/assert_match.ts +++ b/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, diff --git a/assert/assert_not_equals.ts b/assert/assert_not_equals.ts index 6489954a3328..2ad3e122322b 100644 --- a/assert/assert_not_equals.ts +++ b/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(actual: T, expected: T, msg?: string) { if (!equal(actual, expected)) { diff --git a/assert/assert_not_instance_of.ts b/assert/assert_not_instance_of.ts index 794b35b0d433..ad0f267b003a 100644 --- a/assert/assert_not_instance_of.ts +++ b/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( actual: A, diff --git a/assert/assert_not_match.ts b/assert/assert_not_match.ts index 6778ab1751bd..89367f2cec3b 100644 --- a/assert/assert_not_match.ts +++ b/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, diff --git a/assert/assert_not_strict_equals.ts b/assert/assert_not_strict_equals.ts index 89a3b33fb9a9..cc251a05fe91 100644 --- a/assert/assert_not_strict_equals.ts +++ b/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( actual: T, diff --git a/assert/assert_object_match.ts b/assert/assert_object_match.ts index 03c1dd5409bd..7f20f29b379f 100644 --- a/assert/assert_object_match.ts +++ b/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 diff --git a/assert/assert_rejects.ts b/assert/assert_rejects.ts index 541a1ca60352..2a6574801e25 100644 --- a/assert/assert_rejects.ts +++ b/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, @@ -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( fn: () => PromiseLike, diff --git a/assert/assert_strict_equals.ts b/assert/assert_strict_equals.ts index 9075f6f12e60..360d9fa49e40 100644 --- a/assert/assert_strict_equals.ts +++ b/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( actual: unknown, diff --git a/assert/assert_string_includes.ts b/assert/assert_string_includes.ts index 7e12ee509725..385ecbab18c1 100644 --- a/assert/assert_string_includes.ts +++ b/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, diff --git a/assert/assert_throws.ts b/assert/assert_throws.ts index 69f36ab35095..f502604a62ac 100644 --- a/assert/assert_throws.ts +++ b/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( fn: () => unknown, diff --git a/assert/assertion_error.ts b/assert/assertion_error.ts index faaef6a1060f..7606b70711d0 100644 --- a/assert/assertion_error.ts +++ b/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"; diff --git a/assert/equal.ts b/assert/equal.ts index d0e2c90eddba..286018e0de9f 100644 --- a/assert/equal.ts +++ b/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"; * diff --git a/assert/fail.ts b/assert/fail.ts index 617c4fc67b03..f1afef883b7f 100644 --- a/assert/fail.ts +++ b/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}` : "."; diff --git a/assert/unimplemented.ts b/assert/unimplemented.ts index cbdf61a8d0d7..fed7ac4adbd2 100644 --- a/assert/unimplemented.ts +++ b/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}` : "."; diff --git a/assert/unreachable.ts b/assert/unreachable.ts index 6732c9f05327..6f57feed199a 100644 --- a/assert/unreachable.ts +++ b/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"); From 1d2faf44fc17b30649c299e0af9f61ae59f05dfe Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Thu, 30 May 2024 10:22:50 +1000 Subject: [PATCH 2/2] tweak --- assert/assert_equals.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/assert/assert_equals.ts b/assert/assert_equals.ts index 0677f383cccb..4ec27a7ff360 100644 --- a/assert/assert_equals.ts +++ b/assert/assert_equals.ts @@ -4,7 +4,7 @@ import { equal } from "./equal.ts"; import { buildMessage, diff, diffStr, format } from "@std/internal"; import { AssertionError } from "./assertion_error.ts"; -/** The option object for {@linkcode assertEquals}. */ +/** Options for {@linkcode assertEquals}. */ export type AssertEqualsOption = { /** The option for formatting the values. *