docs(yaml): improve yaml document (denoland#5127)

Co-authored-by: Asher Gomez <[email protected]>

Author: kt3k

_tools/check_docs.ts

@@ -71,6 +71,8 @@ const ENTRY_POINTS = [
   "../url/mod.ts",
   "../uuid/mod.ts",
   "../webgpu/mod.ts",
+  "../yaml/parse.ts",
+  "../yaml/stringify.ts",
 ] as const;
 
 const TS_SNIPPET = /```ts[\s\S]*?```/g;

yaml/parse.ts

@@ -4,8 +4,7 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-import type { Schema } from "./schema.ts";
-import { type CbFunction, load, loadAll } from "./_loader/loader.ts";
+import { load, loadAll } from "./_loader/loader.ts";
 import { replaceSchemaNameWithSchemaClass } from "./mod.ts";
 
 /**
@@ -24,18 +23,36 @@ export interface ParseOptions {
    *
    * Schema class or its name.
    */
-  schema?: string | Schema;
+  schema?: "core" | "default" | "failsafe" | "json" | "extended" | unknown;
   /** compatibility with JSON.parse behaviour. */
   json?: boolean;
   /** function to call on warning messages. */
   onWarning?(this: null, e?: Error): void;
 }
 
 /**
- * Parses `content` as single YAML document.
+ * Parse `content` as single YAML document, and return it.
  *
- * Returns a JavaScript object or throws `YAMLError` on error.
- * By default, does not support regexps, functions and undefined. This method is safe for untrusted data.
+ * This function does not support regexps, functions, and undefined by default.
+ * This method is safe for parsing untrusted data.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse } from "@std/yaml/parse";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * const data = parse(`
+ * id: 1
+ * name: Alice
+ * `);
+ *
+ * assertEquals(data, { id: 1, name: "Alice" });
+ * ```
+ *
+ * @throws {YAMLError} Throws error on invalid YAML.
+ * @param content YAML string to parse.
+ * @param options Parsing options.
+ * @returns Parsed document.
  */
 export function parse(content: string, options?: ParseOptions): unknown {
   replaceSchemaNameWithSchemaClass(options);
@@ -47,11 +64,12 @@ export function parse(content: string, options?: ParseOptions): unknown {
  * Same as `parse()`, but understands multi-document sources.
  * Applies iterator to each document if specified, or returns array of documents.
  *
- * @example
+ * @example Usage
  * ```ts
  * import { parseAll } from "@std/yaml/parse";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
- * const data = parseAll(`
+ * parseAll(`
  * ---
  * id: 1
  * name: Alice
@@ -61,20 +79,53 @@ export function parse(content: string, options?: ParseOptions): unknown {
  * ---
  * id: 3
  * name: Eve
- * `);
- * console.log(data);
- * // => [ { id: 1, name: "Alice" }, { id: 2, name: "Bob" }, { id: 3, name: "Eve" } ]
+ * `, (doc: any) => {
+ *   assertEquals(typeof doc, "object");
+ *   assertEquals(typeof doc.id, "number");
+ *   assertEquals(typeof doc.name, "string");
+ * });
  * ```
+ *
+ * @param content YAML string to parse.
+ * @param iterator Function to call on each document.
+ * @param options Parsing options.
  */
 export function parseAll(
   content: string,
-  iterator: CbFunction,
+  iterator: (doc: unknown) => void,
   options?: ParseOptions,
 ): void;
+/**
+ * Same as `parse()`, but understands multi-document sources.
+ * Applies iterator to each document if specified, or returns array of documents.
+ *
+ * @example Usage
+ * ```ts
+ * import { parseAll } from "@std/yaml/parse";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * const data = parseAll(`
+ * ---
+ * id: 1
+ * name: Alice
+ * ---
+ * id: 2
+ * name: Bob
+ * ---
+ * id: 3
+ * name: Eve
+ * `);
+ * assertEquals(data, [ { id: 1, name: "Alice" }, { id: 2, name: "Bob" }, { id: 3, name: "Eve" }]);
+ * ```
+ *
+ * @param content YAML string to parse.
+ * @param options Parsing options.
+ * @returns Array of parsed documents.
+ */
 export function parseAll(content: string, options?: ParseOptions): unknown;
 export function parseAll(
   content: string,
-  iteratorOrOption?: CbFunction | ParseOptions,
+  iteratorOrOption?: ((doc: unknown) => void) | ParseOptions,
   options?: ParseOptions,
 ): unknown {
   if (typeof iteratorOrOption !== "function") {

yaml/schema/mod.ts

@@ -4,7 +4,6 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-import type { Schema } from "../schema.ts";
 import { CORE_SCHEMA } from "./core.ts";
 import { DEFAULT_SCHEMA } from "./default.ts";
 import { EXTENDED_SCHEMA } from "./extended.ts";
@@ -19,7 +18,9 @@ export {
 };
 
 export function replaceSchemaNameWithSchemaClass(
-  options?: { schema?: string | Schema },
+  options?: {
+    schema?: "core" | "default" | "failsafe" | "json" | "extended" | unknown;
+  },
 ) {
   switch (options?.schema) {
     case "core":

yaml/stringify.ts

@@ -4,7 +4,6 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-import type { Schema } from "./schema.ts";
 import { dump } from "./_dumper/dumper.ts";
 import { replaceSchemaNameWithSchemaClass } from "./mod.ts";
 
@@ -33,7 +32,7 @@ export type DumpOptions = {
    *
    * Schema class or its name.
    */
-  schema?: string | Schema;
+  schema?: "core" | "default" | "failsafe" | "json" | "extended" | unknown;
   /**
    * If true, sort keys when dumping YAML in ascending, ASCII character order.
    * If a function, use the function to sort the keys. (default: false)
@@ -68,6 +67,21 @@ export type DumpOptions = {
  * Serializes `data` as a YAML document.
  *
  * You can disable exceptions by setting the skipInvalid option to true.
+ *
+ * @example Usage
+ * ```ts
+ * import { stringify } from "@std/yaml/stringify";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * const data = { id: 1, name: "Alice" };
+ * const yaml = stringify(data);
+ *
+ * assertEquals(yaml, "id: 1\nname: Alice\n");
+ * ```
+ *
+ * @param data The data to serialize.
+ * @param options The options for serialization.
+ * @returns A YAML string.
  */
 export function stringify(
   data: unknown,