📝 Update document comments

Author: lambdalisue

as/mod.ts

@@ -1,6 +1,9 @@
 import { asOptional, asUnoptional } from "./optional.ts";
 import { asReadonly, asUnreadonly } from "./readonly.ts";
 
+/**
+ * Annotation collection for object predicate properties.
+ */
 export const as = {
   Optional: asOptional,
   Readonly: asReadonly,

as/optional.ts

@@ -20,7 +20,6 @@ import {
  * });
  * const a: unknown = {};
  * if (isMyType(a)) {
- *   // a is narrowed to {foo?: string}
  *   const _: {foo?: string} = a;
  * }
  * ```
@@ -64,7 +63,6 @@ export function asOptional<P extends Predicate<unknown>>(
  * });
  * const a: unknown = {foo: "a"};
  * if (isMyType(a)) {
- *   // a is narrowed to {foo: string}
  *   const _: {foo: string} = a;
  * }
  * ```

as/readonly.ts

@@ -1,5 +1,5 @@
 import { rewriteName } from "../_funcutil.ts";
-import type { Predicate, PredicateType } from "../type.ts";
+import type { Predicate } from "../type.ts";
 import {
   annotate,
   hasAnnotation,
@@ -20,7 +20,6 @@ import {
  * });
  * const a: unknown = {};
  * if (isMyType(a)) {
- *   // a is narrowed to {readonly foo: string}
  *   const _: {readonly foo: string} = a;
  * }
  * ```
@@ -55,7 +54,6 @@ export function asReadonly<P extends Predicate<unknown>>(
  * });
  * const a: unknown = {foo: "a"};
  * if (isMyType(a)) {
- *   // a is narrowed to {foo: string}
  *   const _: {foo: string} = a;
  * }
  * ```

assert.ts

@@ -1,11 +1,17 @@
 import type { Predicate } from "./type.ts";
 
+/**
+ * A factory function that generates assertion error messages.
+ */
 export type AssertMessageFactory = (
   x: unknown,
   pred: Predicate<unknown>,
   name?: string,
 ) => string;
 
+/**
+ * The default factory function used to generate assertion error messages.
+ */
 export const defaultAssertMessageFactory: AssertMessageFactory = (
   x,
   pred,
@@ -26,7 +32,7 @@ let assertMessageFactory = defaultAssertMessageFactory;
  */
 export class AssertError extends Error {
   /**
-   * Constructs a new `AssertError` instance.
+   * Constructs a new instance.
    * @param message The error message.
    */
   constructor(message?: string) {
@@ -42,8 +48,7 @@ export class AssertError extends Error {
 
 /**
  * Sets the factory function used to generate assertion error messages.
- * @param factory The factory function.
- * @example
+ *
  * ```ts
  * import { is, setAssertMessageFactory } from "@core/unknownutil";
  *
@@ -59,6 +64,8 @@ export class AssertError extends Error {
  *   }
  * });
  * ```
+ *
+ * @param factory The factory function.
  */
 export function setAssertMessageFactory(factory: AssertMessageFactory): void {
   assertMessageFactory = factory;
@@ -67,6 +74,8 @@ export function setAssertMessageFactory(factory: AssertMessageFactory): void {
 /**
  * Asserts that the given value satisfies the provided predicate.
  *
+ * It throws {@linkcode AssertError} if the value does not satisfy the predicate.
+ *
  * ```ts
  * import { assert, is } from "@core/unknownutil";
  *
@@ -78,8 +87,7 @@ export function setAssertMessageFactory(factory: AssertMessageFactory): void {
  * @param x The value to be asserted.
  * @param pred The predicate function to test the value against.
  * @param options Optional configuration for the assertion.
- * @returns Nothing. The function has a return type of `asserts x is T` to help TypeScript narrow down the type of `x` after the assertion.
- * @throws {AssertError} If the value does not satisfy the predicate.
+ * @returns The function has a return type of `asserts x is T` to help TypeScript narrow down the type of `x` after the assertion.
  */
 export function assert<T>(
   x: unknown,

ensure.ts

@@ -4,6 +4,8 @@ import { assert } from "./assert.ts";
 /**
  * Ensures that the given value satisfies the provided predicate.
  *
+ * It throws {@linkcode AssertError} if the value does not satisfy the predicate.
+ *
  * ```ts
  * import { ensure, is } from "@core/unknownutil";
  *
@@ -15,7 +17,6 @@ import { assert } from "./assert.ts";
  * @param pred The predicate function to test the value against.
  * @param options Optional configuration for the assertion.
  * @returns The input value `x`.
- * @throws {AssertError} If the value does not satisfy the predicate.
  */
 export function ensure<T>(
   x: unknown,

is/any.ts

@@ -6,7 +6,6 @@
  *
  * const a = "a";
  * if (is.Any(a)) {
- *   // a is narrowed to any
  *   const _: any = a;
  * }
  * ```

is/array.ts

@@ -6,7 +6,6 @@
  *
  * const a: unknown = [0, 1, 2];
  * if (is.Array(a)) {
- *   // a is narrowed to unknown[]
  *   const _: unknown[] = a;
  * }
  * ```

is/array_of.ts

@@ -13,7 +13,6 @@ import { isArray } from "./array.ts";
  * const isMyType = is.ArrayOf(is.String);
  * const a: unknown = ["a", "b", "c"];
  * if (isMyType(a)) {
- *   // a is narrowed to string[]
  *   const _: string[] = a;
  * }
  * ```

is/async_function.ts

@@ -8,7 +8,6 @@ const objectToString = Object.prototype.toString;
  *
  * const a: unknown = async () => {};
  * if (is.AsyncFunction(a)) {
- *   // a is narrowed to (...args: unknown[]) => Promise<unknown>
  *   const _: ((...args: unknown[]) => Promise<unknown>) = a;
  * }
  * ```

is/bigint.ts

@@ -6,7 +6,6 @@
  *
  * const a: unknown = 0n;
  * if (is.Bigint(a)) {
- *   // a is narrowed to bigint
  *   const _: bigint = a;
  * }
  * ```