From 820b78235732401fd366f077ea62d262e465a672 Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Fri, 5 Jul 2024 13:52:50 +1000 Subject: [PATCH 1/3] docs(yaml): improve documentation --- yaml/parse.ts | 35 ++++++++++++++++++++++++----------- yaml/stringify.ts | 4 +--- 2 files changed, 25 insertions(+), 14 deletions(-) diff --git a/yaml/parse.ts b/yaml/parse.ts index d019cd4def01..5914a5bb6fe0 100644 --- a/yaml/parse.ts +++ b/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` (default) + * - {@linkcode https://yaml.org/spec/1.2.2/#101-failsafe-schema | failsafe} + * - {@linkcode https://yaml.org/spec/1.2.2/#102-json-schema | json} + * - {@linkcode https://yaml.org/spec/1.2.2/#103-core-schema | core} + * + * @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 diff --git a/yaml/stringify.ts b/yaml/stringify.ts index dfba209a091f..fc22959c3c64 100644 --- a/yaml/stringify.ts +++ b/yaml/stringify.ts @@ -10,9 +10,7 @@ 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). */ indent?: number; From 381156a1c90de94a2bccdd67d5dc8b02b4af9787 Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Fri, 5 Jul 2024 16:14:02 +1000 Subject: [PATCH 2/3] work --- yaml/_dumper.ts | 2 +- yaml/mod.ts | 14 ++++++------ yaml/parse.ts | 6 ++--- yaml/stringify.ts | 57 +++++++++++++++++++++++++++++++++++------------ 4 files changed, 54 insertions(+), 25 deletions(-) diff --git a/yaml/_dumper.ts b/yaml/_dumper.ts index a542e1eb990c..bb67550346c0 100644 --- a/yaml/_dumper.ts +++ b/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, diff --git a/yaml/mod.ts b/yaml/mod.ts index fbea62edba68..32060a7ce685 100644 --- a/yaml/mod.ts +++ b/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,11 @@ * `); * ``` * + * ## Limitations + * - `binary` type is currently not stable. + * + * For further examples see https://github.com/nodeca/js-yaml/tree/master/examples. + * * @module */ diff --git a/yaml/parse.ts b/yaml/parse.ts index 5914a5bb6fe0..03058b3df417 100644 --- a/yaml/parse.ts +++ b/yaml/parse.ts @@ -11,10 +11,10 @@ import { SCHEMA_MAP } from "./_schema.ts"; export interface ParseOptions { /** * Name of the schema to use. Options includes: - * - `default` (default) + * - `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} - * - {@linkcode https://yaml.org/spec/1.2.2/#102-json-schema | json} - * - {@linkcode https://yaml.org/spec/1.2.2/#103-core-schema | core} * * @default {"default"} */ diff --git a/yaml/stringify.ts b/yaml/stringify.ts index 0c7bd56c5e12..708dcd7f4010 100644 --- a/yaml/stringify.ts +++ b/yaml/stringify.ts @@ -12,58 +12,87 @@ export type { StyleVariant }; /** 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; - /** 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 From 426c0700e367eb3706ec47aa0e25bd03a69e647e Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Sat, 6 Jul 2024 18:21:15 +1000 Subject: [PATCH 3/3] refactor: remove example link --- yaml/mod.ts | 2 -- 1 file changed, 2 deletions(-) diff --git a/yaml/mod.ts b/yaml/mod.ts index 32060a7ce685..10fbcc372eb5 100644 --- a/yaml/mod.ts +++ b/yaml/mod.ts @@ -35,8 +35,6 @@ * ## Limitations * - `binary` type is currently not stable. * - * For further examples see https://github.com/nodeca/js-yaml/tree/master/examples. - * * @module */