docs(yaml): improve documentation

yaml/_dumper.ts

@@ -173,7 +173,7 @@ export class DumperState {
     arrayIndent = true,
     skipInvalid = false,
     flowLevel = -1,
-    styles = null,
+    styles = undefined,
     sortKeys = false,
     lineWidth = 80,
     useAnchors = true,

yaml/mod.ts

@@ -9,13 +9,8 @@
  * Ported from
  * {@link https://github.com/nodeca/js-yaml/commit/665aadda42349dcae869f12040d9b10ef18d12da | js-yaml v3.13.1}.
  *
- * If your YAML contains multiple documents in it, you can use {@linkcode parseAll} for
- * handling it.
- *
- * ## :warning: Limitations
- * - `binary` type is currently not stable.
- *
- * For further examples see https://github.com/nodeca/js-yaml/tree/master/examples.
+ * Use {@linkcode parseAll} for parsing multiple documents in a single YAML
+ * string.
  *
  * ```ts
  * import { parse, stringify } from "@std/yaml";
@@ -37,6 +32,9 @@
  * `);
  * ```
  *
+ * ## Limitations
+ * - `binary` type is currently not stable.
+ *
  * @module
  */
 

yaml/parse.ts

@@ -7,23 +7,36 @@
 import { load, loadDocuments } from "./_loader.ts";
 import { SCHEMA_MAP } from "./_schema.ts";
 
-/**
- * Options for parsing YAML.
- */
+/** Options for {@linkcode parse}. */
 export interface ParseOptions {
-  /** Name of the schema to use.*/
+  /**
+   * Name of the schema to use. Options includes:
+   * - `default` (extends `core` schema)
+   * - {@linkcode https://yaml.org/spec/1.2.2/#103-core-schema | core} (extends `json` schema)
+   * - {@linkcode https://yaml.org/spec/1.2.2/#102-json-schema | json} (extends `failsafe` schema)
+   * - {@linkcode https://yaml.org/spec/1.2.2/#101-failsafe-schema | failsafe}
+   *
+   * @default {"default"}
+   */
   schema?: "core" | "default" | "failsafe" | "json" | "extended";
-  /** compatibility with JSON.parse behaviour. */
+  /**
+   * If `true`, duplicate keys will overwrite previous values. Otherwise,
+   * duplicate keys will throw a {@linkcode YamlError}.
+   *
+   * @default {false}
+   */
   allowDuplicateKeys?: boolean;
-  /** function to call on warning messages. */
+  /**
+   * If defined, a function to call on warning messages taking an
+   * {@linkcode Error} as its only argument.
+   */
   onWarning?(error?: Error): void;
 }
 
 /**
- * Parse `content` as single YAML document, and return it.
+ * Parse and return a YAML string as a parsed YAML document object.
  *
- * This function does not support regexps, functions, and undefined by default.
- * This method is safe for parsing untrusted data.
+ * Note: This does not support functions. Untrusted data is safe to parse.
  *
  * @example Usage
  * ```ts
@@ -51,8 +64,8 @@ export function parse(
 }
 
 /**
- * Same as `parse()`, but understands multi-document sources.
- * Applies iterator to each document if specified, or returns array of documents.
+ * Same as {@linkcode parse}, but understands multi-document YAML sources, and
+ * returns multiple parsed YAML document objects.
  *
  * @example Usage
  * ```ts

yaml/stringify.ts

@@ -10,62 +10,89 @@ import type { StyleVariant } from "./_type.ts";
 
 export type { StyleVariant };
 
-/**
- * The option for strinigfy.
- */
+/** Options for {@linkcode stringify}. */
 export type StringifyOptions = {
-  /** Indentation width to use (in spaces). */
+  /**
+   * Indentation width to use (in spaces).
+   *
+   * @default {2}
+   */
   indent?: number;
-  /** When true, adds an indentation level to array elements */
+  /**
+   * When true, adds an indentation level to array elements.
+   *
+   * @default {true}
+   */
   arrayIndent?: boolean;
   /**
    * Do not throw on invalid types (like function in the safe schema)
    * and skip pairs and single values with such types.
+   *
+   * @default {false}
    */
   skipInvalid?: boolean;
   /**
-   * Specifies level of nesting, when to switch from
-   * block to flow style for collections. -1 means block style everywhere
+   * Specifies level of nesting, when to switch from block to flow style for
+   * collections. `-1` means block style everywhere.
+   *
+   * @default {-1}
    */
   flowLevel?: number;
   /** Each tag may have own set of styles.	- "tag" => "style" map. */
   styles?: Record<string, StyleVariant>;
-  /** Name of the schema to use. */
+  /**
+   * Name of the schema to use. Options includes:
+   * - `default` (extends `core` schema)
+   * - {@linkcode https://yaml.org/spec/1.2.2/#103-core-schema | core} (extends `json` schema)
+   * - {@linkcode https://yaml.org/spec/1.2.2/#102-json-schema | json} (extends `failsafe` schema)
+   * - {@linkcode https://yaml.org/spec/1.2.2/#101-failsafe-schema | failsafe}
+   *
+   * @default {"default"}
+   */
   schema?: "core" | "default" | "failsafe" | "json" | "extended";
   /**
    * If true, sort keys when dumping YAML in ascending, ASCII character order.
-   * If a function, use the function to sort the keys. (default: false)
+   * If a function, use the function to sort the keys.
    * If a function is specified, the function must return a negative value
    * if first argument is less than second argument, zero if they're equal
    * and a positive value otherwise.
+   *
+   * @default {false}
    */
   sortKeys?: boolean | ((a: string, b: string) => number);
-  /** Set max line width. (default: 80) */
+  /**
+   * Set max line width.
+   *
+   * @default {80}
+   */
   lineWidth?: number;
   /**
-   * If false, don't convert duplicate objects
-   * into references (default: true)
+   * If false, don't convert duplicate objects into references.
+   *
+   * @default {true}
    */
   useAnchors?: boolean;
   /**
    * If false don't try to be compatible with older yaml versions.
    * Currently: don't quote "yes", "no" and so on,
-   * as required for YAML 1.1 (default: true)
+   * as required for YAML 1.1.
+   *
+   * @default {true}
    */
   compatMode?: boolean;
   /**
    * If true flow sequences will be condensed, omitting the
    * space between `key: value` or `a, b`. Eg. `'[a,b]'` or `{a:{b:c}}`.
    * Can be useful when using yaml for pretty URL query params
-   * as spaces are %-encoded. (default: false).
+   * as spaces are %-encoded.
+   *
+   * @default {false}
    */
   condenseFlow?: boolean;
 };
 
 /**
- * Serializes `data` as a YAML document.
- *
- * You can disable exceptions by setting the skipInvalid option to true.
+ * Converts a JavaScript object or value to a YAML document string.
  *
  * @example Usage
  * ```ts