add descriptions to leafs

docs/modules/Schema.ts.md

@@ -260,6 +260,7 @@ Added in v1.0.0
 - [renaming](#renaming)
   - [rename](#rename)
 - [string constructors](#string-constructors)
+  - [Char](#char)
   - [Lowercased](#lowercased)
   - [NonEmpty](#nonempty)
   - [Trimmed](#trimmed)
@@ -2729,6 +2730,8 @@ Added in v1.0.0
 
 ## between
 
+This filter checks whether the provided number falls within the specified minimum and maximum values.
+
 **Signature**
 
 ```ts
@@ -2743,6 +2746,10 @@ Added in v1.0.0
 
 ## finite
 
+Ensures that the provided value is a finite number.
+
+This schema filters out non-finite numeric values, allowing only finite numbers to pass through.
+
 **Signature**
 
 ```ts
@@ -2755,6 +2762,8 @@ Added in v1.0.0
 
 ## greaterThan
 
+This filter checks whether the provided number is greater than the specified minimum.
+
 **Signature**
 
 ```ts
@@ -2768,6 +2777,8 @@ Added in v1.0.0
 
 ## greaterThanOrEqualTo
 
+This filter checks whether the provided number is greater than or equal to the specified minimum.
+
 **Signature**
 
 ```ts
@@ -2793,6 +2804,8 @@ Added in v1.0.0
 
 ## lessThan
 
+This filter checks whether the provided number is less than the specified maximum.
+
 **Signature**
 
 ```ts
@@ -2806,6 +2819,8 @@ Added in v1.0.0
 
 ## lessThanOrEqualTo
 
+This schema checks whether the provided number is less than or equal to the specified maximum.
+
 **Signature**
 
 ```ts
@@ -3140,6 +3155,18 @@ Added in v1.0.0
 
 # string constructors
 
+## Char
+
+A schema representing a single character.
+
+**Signature**
+
+```ts
+export declare const Char: Schema<string, string>
+```
+
+Added in v1.0.0
+
 ## Lowercased
 
 **Signature**
@@ -3172,6 +3199,11 @@ Added in v1.0.0
 
 ## ULID
 
+Represents a Universally Unique Lexicographically Sortable Identifier (ULID).
+
+ULIDs are designed to be compact, URL-safe, and ordered, making them suitable for use as identifiers.
+This schema ensures that the provided string adheres to the standard ULID format.
+
 **Signature**
 
 ```ts
@@ -3182,6 +3214,10 @@ Added in v1.0.0
 
 ## UUID
 
+Represents a Universally Unique Identifier (UUID).
+
+This schema ensures that the provided string adheres to the standard UUID format.
+
 **Signature**
 
 ```ts

src/AST.ts

@@ -319,8 +319,7 @@ export const isLiteral = (ast: AST): ast is Literal => ast._tag === "Literal"
 
 /** @internal */
 export const _null = createLiteral(null, {
-  [IdentifierAnnotationId]: "null",
-  [DescriptionAnnotationId]: "null"
+  [IdentifierAnnotationId]: "null"
 })
 
 /**
@@ -619,7 +618,8 @@ export const objectKeyword: ObjectKeyword = {
   _tag: "ObjectKeyword",
   annotations: {
     [IdentifierAnnotationId]: "object",
-    [TitleAnnotationId]: "object"
+    [TitleAnnotationId]: "object",
+    [DescriptionAnnotationId]: "an object in the TypeScript meaning, i.e. the `object` type"
   }
 }
 

src/ArrayFormatter.ts

@@ -31,7 +31,7 @@ const format = (self: ParseIssue, path: ReadonlyArray<PropertyKey> = []): Array<
       return [{
         _tag,
         path,
-        message: `Unexpected, expected ${Format.formatAST(self.expected)}`
+        message: `Unexpected, expected ${Format.formatAST(self.expected, true)}`
       }]
     case "Union":
       return ReadonlyArray.flatMap(self.errors, (e) => {

src/Format.ts

@@ -107,16 +107,25 @@ const formatTemplateLiteral = (ast: AST.TemplateLiteral): string =>
     formatTemplateLiteralSpan(span) + span.literal
   ).join("") + "`"
 
-const getExpected = (ast: AST.AST, verbose: boolean): Option.Option<string> =>
-  verbose ?
-    AST.getDescriptionAnnotation(ast).pipe(
-      Option.orElse(() => AST.getTitleAnnotation(ast)),
-      Option.orElse(() => AST.getIdentifierAnnotation(ast))
-    ) :
-    AST.getIdentifierAnnotation(ast).pipe(
-      Option.orElse(() => AST.getTitleAnnotation(ast)),
-      Option.orElse(() => AST.getDescriptionAnnotation(ast))
+const getExpected = (ast: AST.AST, verbose: boolean): Option.Option<string> => {
+  if (verbose) {
+    const description = AST.getDescriptionAnnotation(ast).pipe(
+      Option.orElse(() => AST.getTitleAnnotation(ast))
     )
+    return Option.match(AST.getIdentifierAnnotation(ast), {
+      onNone: () => description,
+      onSome: (identifier) =>
+        Option.match(description, {
+          onNone: () => Option.some(identifier),
+          onSome: (description) => Option.some(`${identifier} (${description})`)
+        })
+    })
+  }
+  return AST.getIdentifierAnnotation(ast).pipe(
+    Option.orElse(() => AST.getTitleAnnotation(ast)),
+    Option.orElse(() => AST.getDescriptionAnnotation(ast))
+  )
+}
 
 const formatTuple = (ast: AST.Tuple): string => {
   const formattedElements = ast.elements.map((element) =>