docs: add documentations of is/as

Author: lambdalisue

as/mod.ts

@@ -1,12 +1,100 @@
-import { asOptional, asUnoptional } from "./optional.ts";
-import { asReadonly, asUnreadonly } from "./readonly.ts";
+// NOTE: This file is generated by gen-mod.ts
+import { asOptional } from "./optional.ts";
+import { asReadonly } from "./readonly.ts";
+import { asUnoptional } from "./optional.ts";
+import { asUnreadonly } from "./readonly.ts";
 
-/**
- * Annotation collection for object predicate properties.
- */
 export const as = {
+  /**
+   * Annotate the given predicate function as optional.
+   *
+   * Use this function to annotate a predicate function of `predObj` in {@linkcode isObjectOf}.
+   *
+   * Note that the annotated predicate function will return `true` if the type of `x` is `T` or `undefined`, indicating that
+   * this function is not just for annotation but it also changes the behavior of the predicate function.
+   *
+   * Use {@linkcode asUnoptional} to remove the annotation.
+   * Use {@linkcode hasOptional} to check if a predicate function has annotated with this function.
+   *
+   * To enhance performance, users are advised to cache the return value of this function and mitigate the creation cost.
+   *
+   * ```ts
+   * import { as, is } from "@core/unknownutil";
+   *
+   * const isMyType = is.ObjectOf({
+   *   foo: as.Optional(is.String),
+   * });
+   * const a: unknown = {};
+   * if (isMyType(a)) {
+   *   const _: {foo?: string} = a;
+   * }
+   * ```
+   */
   Optional: asOptional,
+  /**
+   * Annotate the given predicate function as readonly.
+   *
+   * Use this function to annotate a predicate function of `predObj` in {@linkcode isObjectOf}.
+   *
+   * Use {@linkcode asUnreadonly} to remove the annotation.
+   * Use {@linkcode hasReadonly} to check if a predicate function has annotated with this function.
+   *
+   * To enhance performance, users are advised to cache the return value of this function and mitigate the creation cost.
+   *
+   * ```ts
+   * import { as, is } from "@core/unknownutil";
+   *
+   * const isMyType = is.ObjectOf({
+   *   foo: as.Readonly(is.String),
+   * });
+   * const a: unknown = {};
+   * if (isMyType(a)) {
+   *   const _: {readonly foo: string} = a;
+   * }
+   * ```
+   */
   Readonly: asReadonly,
+  /**
+   * Unannotate the annotated predicate function with {@linkcode asOptional}.
+   *
+   * Use this function to unannotate a predicate function of `predObj` in {@linkcode isObjectOf}.
+   *
+   * Note that the annotated predicate function will return `true` if the type of `x` is `T`, indicating that
+   * this function is not just for annotation but it also changes the behavior of the predicate function.
+   *
+   * To enhance performance, users are advised to cache the return value of this function and mitigate the creation cost.
+   *
+   * ```ts
+   * import { as, is } from "@core/unknownutil";
+   *
+   * const isMyType = is.ObjectOf({
+   *   foo: as.Unoptional(as.Optional(is.String)),
+   * });
+   * const a: unknown = {foo: "a"};
+   * if (isMyType(a)) {
+   *   const _: {foo: string} = a;
+   * }
+   * ```
+   */
   Unoptional: asUnoptional,
+  /**
+   * Unannotate the annotated predicate function with {@linkcode asReadonly}.
+   *
+   * Use this function to unannotate a predicate function of `predObj` in {@linkcode isObjectOf}.
+   *
+   * To enhance performance, users are advised to cache the return value of this function and mitigate the creation cost.
+   *
+   * ```ts
+   * import { as, is } from "@core/unknownutil";
+   *
+   * const isMyType = is.ObjectOf({
+   *   foo: as.Unreadonly(as.Readonly(is.String)),
+   * });
+   * const a: unknown = {foo: "a"};
+   * if (isMyType(a)) {
+   *   const _: {foo: string} = a;
+   * }
+   * ```
+   */
   Unreadonly: asUnreadonly,
 };