💪 Improve docs/tests/types of as module

Author: lambdalisue

_annotation.ts

@@ -32,14 +32,14 @@ export function hasAnnotation<F extends Fn, N extends string>(
 /**
  * Annotation for optional.
  */
-export type WithOptional<T = unknown> = {
+export type AsOptional<T = unknown> = {
   optional: Predicate<T>;
 };
 
 /**
  * Annotation for readonly.
  */
-export type WithReadonly<T = unknown> = {
+export type AsReadonly<T = unknown> = {
   readonly: Predicate<T>;
 };
 

as/__snapshots__/optional_test.ts.snap

@@ -2,13 +2,21 @@ import { rewriteName } from "../_funcutil.ts";
 import type { Predicate, PredicateType } from "../type.ts";
 import {
   annotate,
+  type AsOptional,
   hasAnnotation,
   unannotate,
-  type WithOptional,
 } from "../_annotation.ts";
 
 /**
- * Return an `Optional` annotated type predicate function that returns `true` if the type of `x` is `T` or `undefined`.
+ * 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.
  *
@@ -29,16 +37,16 @@ export function asOptional<P extends Predicate<unknown>>(
 ):
   & Extract<P, Predicate<PredicateType<P>>>
   & Predicate<PredicateType<P> | undefined>
-  & WithOptional<PredicateType<P>> {
+  & AsOptional<PredicateType<P>> {
   if (hasAnnotation(pred, "optional")) {
     return pred as
       & Extract<P, Predicate<PredicateType<P>>>
       & Predicate<PredicateType<P> | undefined>
-      & WithOptional<PredicateType<P>>;
+      & AsOptional<PredicateType<P>>;
   }
   return rewriteName(
     annotate(
-      (x: unknown) => x === undefined || pred(x),
+      (x) => x === undefined || pred(x),
       "optional",
       pred,
     ),
@@ -47,11 +55,16 @@ export function asOptional<P extends Predicate<unknown>>(
   ) as unknown as
     & Extract<P, Predicate<PredicateType<P>>>
     & Predicate<PredicateType<P> | undefined>
-    & WithOptional<PredicateType<P>>;
+    & AsOptional<PredicateType<P>>;
 }
 
 /**
- * Return an `Optional` un-annotated type predicate function that returns `true` if the type of `x` is `T`.
+ * 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.
  *
@@ -89,6 +102,6 @@ export function hasOptional<
     : never,
 >(
   pred: P,
-): pred is P & WithOptional<T> {
+): pred is P & AsOptional<T> {
   return hasAnnotation(pred, "optional");
 }