From d13ef17a5d805602a14c19feccfb46dede33df74 Mon Sep 17 00:00:00 2001 From: Yusuke Tanaka Date: Mon, 27 May 2024 18:14:52 -0700 Subject: [PATCH] docs(front-matter): improve docs for stabilization (#4789) This commit improves docs of the front-matter module. Specifically, the following things are done: - Use `@example` where appropriate to render the examples more beautifully - Split the big example attached to `createExtractor` function into smaller pieces so that each one has minimal yet meaningful example - Add `@returns` to the `test` function - Deduplicate `Format` type definition - Add a brief description to `Format` type Towards #3764 --------- Co-authored-by: Asher Gomez --- _tools/check_docs.ts | 1 + front_matter/_test_utils.ts | 10 +-- front_matter/_types.ts | 7 ++ front_matter/any.ts | 8 +- front_matter/any_test.ts | 16 ++-- front_matter/create_extractor.ts | 105 ++++++++++++++++++-------- front_matter/create_extractor_test.ts | 54 ++++++------- front_matter/json.ts | 11 ++- front_matter/json_test.ts | 4 +- front_matter/mod.ts | 18 +++-- front_matter/test.ts | 59 +++++++++++++-- front_matter/toml.ts | 11 ++- front_matter/toml_test.ts | 8 +- front_matter/yaml.ts | 11 ++- front_matter/yaml_test.ts | 8 +- 15 files changed, 219 insertions(+), 112 deletions(-) create mode 100644 front_matter/_types.ts diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index a3295f52c..b3ad49f23 100644 --- a/_tools/check_docs.ts +++ b/_tools/check_docs.ts @@ -34,6 +34,7 @@ const ENTRY_POINTS = [ "../datetime/mod.ts", "../encoding/mod.ts", "../expect/mod.ts", + "../front_matter/mod.ts", "../http/mod.ts", "../internal/mod.ts", "../jsonc/mod.ts", diff --git a/front_matter/_test_utils.ts b/front_matter/_test_utils.ts index 15bf649e3..82e15db67 100644 --- a/front_matter/_test_utils.ts +++ b/front_matter/_test_utils.ts @@ -77,7 +77,7 @@ export function runExtractTypeErrorTests( }); } -export async function runExtractJSONTests( +export async function runExtractJsonTests( extractFn: ExtractFn, ) { const str = await Deno.readTextFile(resolveTestDataPath("json.md")); @@ -110,7 +110,7 @@ export async function runExtractJSONTests( ); } -export async function runExtractYAMLTests1( +export async function runExtractYamlTests1( extractFn: ExtractFn, ) { const str = await Deno.readTextFile(resolveTestDataPath("yaml1.md")); @@ -138,7 +138,7 @@ expanded-description: with some --- crazy stuff in it`, ); } -export async function runExtractYAMLTests2( +export async function runExtractYamlTests2( extractFn: ExtractFn, ) { const str = await Deno.readTextFile(resolveTestDataPath("yaml2.md")); @@ -166,7 +166,7 @@ expanded-description: with some --- crazy stuff in it`, ); } -export async function runExtractTOMLTests( +export async function runExtractTomlTests( extractFn: ExtractFn, ) { const str = await Deno.readTextFile(resolveTestDataPath("toml.md")); @@ -194,7 +194,7 @@ tags = ['toml', 'front-matter'] ); } -export async function runExtractTOMLTests2( +export async function runExtractTomlTests2( extractFn: ExtractFn, ) { const str = await Deno.readTextFile(resolveTestDataPath("toml2.md")); diff --git a/front_matter/_types.ts b/front_matter/_types.ts new file mode 100644 index 000000000..ddaa2cf9c --- /dev/null +++ b/front_matter/_types.ts @@ -0,0 +1,7 @@ +// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. + +/** + * Supported format for front matter. `"unknown"` is used when auto format + * detection logic fails. + */ +export type Format = "yaml" | "toml" | "json" | "unknown"; diff --git a/front_matter/any.ts b/front_matter/any.ts index f98ef1ae9..e169f5d74 100644 --- a/front_matter/any.ts +++ b/front_matter/any.ts @@ -5,8 +5,8 @@ import { type Extractor, type Parser, } from "./create_extractor.ts"; -import { parse as parseYAML } from "@std/yaml/parse"; -import { parse as parseTOML } from "@std/toml/parse"; +import { parse as parseYaml } from "@std/yaml/parse"; +import { parse as parseToml } from "@std/toml/parse"; /** * Extracts and parses {@link https://yaml.org | YAML}, {@link https://toml.io | @@ -31,7 +31,7 @@ import { parse as parseTOML } from "@std/toml/parse"; * ``` */ export const extract: Extractor = createExtractor({ - yaml: parseYAML as Parser, - toml: parseTOML as Parser, + yaml: parseYaml as Parser, + toml: parseToml as Parser, json: JSON.parse as Parser, }); diff --git a/front_matter/any_test.ts b/front_matter/any_test.ts index 090498c7d..7fe1ee3eb 100644 --- a/front_matter/any_test.ts +++ b/front_matter/any_test.ts @@ -3,11 +3,11 @@ import { test } from "./test.ts"; import { extract } from "./any.ts"; import { - runExtractJSONTests, - runExtractTOMLTests, + runExtractJsonTests, + runExtractTomlTests, runExtractTypeErrorTests, - runExtractYAMLTests1, - runExtractYAMLTests2, + runExtractYamlTests1, + runExtractYamlTests2, runTestInvalidInputTests, runTestValidInputTests, } from "./_test_utils.ts"; @@ -27,11 +27,11 @@ Deno.test("extract() extracts type error on invalid input", () => { }); Deno.test("extract() parses yaml delineate by `---`", async () => { - await runExtractYAMLTests1(extract); + await runExtractYamlTests1(extract); }); Deno.test("extract() parses yaml delineate by `---yaml`", async () => { - await runExtractYAMLTests2(extract); + await runExtractYamlTests2(extract); }); // JSON // @@ -49,7 +49,7 @@ Deno.test("extract() extracts type error on invalid json input", () => { }); Deno.test("extract() parses json delineate by ---json", async () => { - await runExtractJSONTests(extract); + await runExtractJsonTests(extract); }); // TOML // @@ -67,5 +67,5 @@ Deno.test("extract() extracts type error on invalid toml input", () => { }); Deno.test("extract() parses toml delineate by ---toml", async () => { - await runExtractTOMLTests(extract); + await runExtractTomlTests(extract); }); diff --git a/front_matter/create_extractor.ts b/front_matter/create_extractor.ts index 411abdd4c..f6352288f 100644 --- a/front_matter/create_extractor.ts +++ b/front_matter/create_extractor.ts @@ -1,8 +1,7 @@ // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. import { EXTRACT_REGEXP_MAP, RECOGNIZE_REGEXP_MAP } from "./_formats.ts"; - -type Format = "yaml" | "toml" | "json" | "unknown"; +import type { Format } from "./_types.ts"; /** Return type for {@linkcode Extractor}. */ export type Extract = { @@ -35,21 +34,12 @@ function _extract( } /** - * Recognizes the format of the front matter in a string. Supports YAML, TOML and JSON. + * Recognizes the format of the front matter in a string. + * Supports {@link https://yaml.org | YAML}, {@link https://toml.io | TOML} and + * {@link https://www.json.org/ | JSON}. * * @param str String to recognize. * @param formats A list of formats to recognize. Defaults to all supported formats. - * - * ```ts - * import { recognize } from "@std/front-matter"; - * import { assertEquals } from "@std/assert/assert-equals"; - * - * assertEquals(recognize("---\ntitle: Three dashes marks the spot\n---\n"), "yaml"); - * assertEquals(recognize("---toml\ntitle = 'Three dashes followed by format marks the spot'\n---\n"), "toml"); - * assertEquals(recognize("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\n"), "json"); - * assertEquals(recognize("---xml\nThree dashes marks the spot\n---\n"), "unknown"); - * - * assertEquals(recognize("---json\nThree dashes marks the spot\n---\n", ["yaml"]), "unknown"); */ function recognize(str: string, formats?: Format[]): Format { if (!formats) { @@ -72,53 +62,102 @@ function recognize(str: string, formats?: Format[]): Format { } /** - * Factory that creates a function that extracts front matter from a string with the given parsers. - * Supports YAML, TOML and JSON. + * Factory that creates a function that extracts front matter from a string with + * the given parsers. Supports {@link https://yaml.org | YAML}, + * {@link https://toml.io | TOML} and {@link https://www.json.org/ | JSON}. + * + * For simple use cases where you know which format to parse in advance, use the + * pre-built extractors: + * + * - {@linkcode https://jsr.io/@std/front-matter/doc/yaml/~/extract | extractYaml} + * - {@linkcode https://jsr.io/@std/front-matter/doc/toml/~/extract | extractToml} + * - {@linkcode https://jsr.io/@std/front-matter/doc/json/~/extract | extractJson} * * @param formats A descriptor containing Format-parser pairs to use for each format. * @returns A function that extracts front matter from a string with the given parsers. * + * @example Extract YAML front matter * ```ts * import { createExtractor, Parser } from "@std/front-matter"; * import { assertEquals } from "@std/assert/assert-equals"; - * import { parse as parseYAML } from "@std/yaml/parse"; - * import { parse as parseTOML } from "@std/toml/parse"; - * const extractYAML = createExtractor({ yaml: parseYAML as Parser }); - * const extractTOML = createExtractor({ toml: parseTOML as Parser }); - * const extractJSON = createExtractor({ json: JSON.parse as Parser }); - * const extractYAMLOrJSON = createExtractor({ - * yaml: parseYAML as Parser, - * json: JSON.parse as Parser, - * }); + * import { parse as parseYaml } from "@std/yaml/parse"; * - * let { attrs, body, frontMatter } = extractYAML<{ title: string }>("---\ntitle: Three dashes marks the spot\n---\nferret"); + * const extractYaml = createExtractor({ yaml: parseYaml as Parser }); + * const { attrs, body, frontMatter } = extractYaml<{ title: string }>( + * `--- + * title: Three dashes marks the spot + * --- + * ferret`); * assertEquals(attrs.title, "Three dashes marks the spot"); * assertEquals(body, "ferret"); * assertEquals(frontMatter, "title: Three dashes marks the spot"); + * ``` * - * ({ attrs, body, frontMatter } = extractTOML<{ title: string }>("---toml\ntitle = 'Three dashes followed by format marks the spot'\n---\n")); + * @example Extract TOML front matter + * ```ts + * import { createExtractor, Parser } from "@std/front-matter"; + * import { assertEquals } from "@std/assert/assert-equals"; + * import { parse as parseToml } from "@std/toml/parse"; + * + * const extractToml = createExtractor({ toml: parseToml as Parser }); + * const { attrs, body, frontMatter } = extractToml<{ title: string }>( + * `---toml + * title = 'Three dashes followed by format marks the spot' + * --- + * `); * assertEquals(attrs.title, "Three dashes followed by format marks the spot"); * assertEquals(body, ""); * assertEquals(frontMatter, "title = 'Three dashes followed by format marks the spot'"); + * ``` * - * ({ attrs, body, frontMatter } = extractJSON<{ title: string }>("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\ngoat")); + * @example Extract JSON front matter + * ```ts + * import { createExtractor, Parser } from "@std/front-matter"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const extractJson = createExtractor({ json: JSON.parse as Parser }); + * const { attrs, body, frontMatter } = extractJson<{ title: string }>( + * `---json + * {"title": "Three dashes followed by format marks the spot"} + * --- + * goat`); * assertEquals(attrs.title, "Three dashes followed by format marks the spot"); * assertEquals(body, "goat"); - * assertEquals(frontMatter, "{\"title\": \"Three dashes followed by format marks the spot\"}"); + * assertEquals(frontMatter, `{"title": "Three dashes followed by format marks the spot"}`); + * ``` * - * ({ attrs, body, frontMatter } = extractYAMLOrJSON<{ title: string }>("---\ntitle: Three dashes marks the spot\n---\nferret")); + * @example Extract YAML or JSON front matter + * ```ts + * import { createExtractor, Parser } from "@std/front-matter"; + * import { assertEquals } from "@std/assert/assert-equals"; + * import { parse as parseYaml } from "@std/yaml/parse"; + * + * const extractYamlOrJson = createExtractor({ + * yaml: parseYaml as Parser, + * json: JSON.parse as Parser, + * }); + * + * let { attrs, body, frontMatter } = extractYamlOrJson<{ title: string }>( + * `--- + * title: Three dashes marks the spot + * --- + * ferret`); * assertEquals(attrs.title, "Three dashes marks the spot"); * assertEquals(body, "ferret"); * assertEquals(frontMatter, "title: Three dashes marks the spot"); * - * ({ attrs, body, frontMatter } = extractYAMLOrJSON<{ title: string }>("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\ngoat")); + * ({ attrs, body, frontMatter } = extractYamlOrJson<{ title: string }>( + * `---json + * {"title": "Three dashes followed by format marks the spot"} + * --- + * goat`)); * assertEquals(attrs.title, "Three dashes followed by format marks the spot"); * assertEquals(body, "goat"); - * assertEquals(frontMatter, "{\"title\": \"Three dashes followed by format marks the spot\"}"); + * assertEquals(frontMatter, `{"title": "Three dashes followed by format marks the spot"}`); * ``` */ export function createExtractor( - formats: Partial>, + formats: Partial>, ): Extractor { const formatKeys = Object.keys(formats) as Format[]; diff --git a/front_matter/create_extractor_test.ts b/front_matter/create_extractor_test.ts index d3000e745..1a3b0df0c 100644 --- a/front_matter/create_extractor_test.ts +++ b/front_matter/create_extractor_test.ts @@ -1,43 +1,43 @@ // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. import { assertThrows } from "@std/assert"; -import { parse as parseYAML } from "@std/yaml/parse"; -import { parse as parseTOML } from "@std/toml/parse"; +import { parse as parseYaml } from "@std/yaml/parse"; +import { parse as parseToml } from "@std/toml/parse"; import { resolveTestDataPath, - runExtractJSONTests, - runExtractTOMLTests, + runExtractJsonTests, + runExtractTomlTests, runExtractTypeErrorTests, - runExtractYAMLTests1, - runExtractYAMLTests2, + runExtractYamlTests1, + runExtractYamlTests2, } from "./_test_utils.ts"; import { createExtractor, type Parser } from "./create_extractor.ts"; -const extractYAML = createExtractor({ "yaml": parseYAML as Parser }); -const extractTOML = createExtractor({ "toml": parseTOML as Parser }); -const extractJSON = createExtractor({ "json": JSON.parse as Parser }); -const extractYAMLOrJSON = createExtractor({ - "yaml": parseYAML as Parser, +const extractYaml = createExtractor({ "yaml": parseYaml as Parser }); +const extractToml = createExtractor({ "toml": parseToml as Parser }); +const extractJson = createExtractor({ "json": JSON.parse as Parser }); +const extractYamlOrJson = createExtractor({ + "yaml": parseYaml as Parser, "json": JSON.parse as Parser, }); const extractAny = createExtractor({ - "yaml": parseYAML as Parser, + "yaml": parseYaml as Parser, "json": JSON.parse as Parser, - "toml": parseTOML as Parser, + "toml": parseToml as Parser, }); // YAML // Deno.test("createExtractor() extracts yaml type error on invalid input", () => { - runExtractTypeErrorTests("yaml", extractYAML); + runExtractTypeErrorTests("yaml", extractYaml); }); Deno.test("createExtractor() parses yaml delineate by `---`", async () => { - await runExtractYAMLTests1(extractYAML); + await runExtractYamlTests1(extractYaml); }); Deno.test("createExtractor() parses yaml delineate by `---yaml`", async () => { - await runExtractYAMLTests2(extractYAML); + await runExtractYamlTests2(extractYaml); }); Deno.test({ @@ -61,34 +61,34 @@ Deno.test({ // JSON // Deno.test("createExtractor() extracts json type error on invalid input", () => { - runExtractTypeErrorTests("json", extractJSON); + runExtractTypeErrorTests("json", extractJson); }); Deno.test("createExtractor() parses json delineate by ---json", async () => { - await runExtractJSONTests(extractJSON); + await runExtractJsonTests(extractJson); }); // TOML // Deno.test("createExtractor() extracts toml type error on invalid input", () => { - runExtractTypeErrorTests("toml", extractTOML); + runExtractTypeErrorTests("toml", extractToml); }); Deno.test("createExtractor() parses toml delineate by ---toml", async () => { - await runExtractTOMLTests(extractTOML); + await runExtractTomlTests(extractToml); }); // MULTIPLE FORMATS // Deno.test("createExtractor() parses yaml or json input", async () => { - await runExtractYAMLTests1(extractYAMLOrJSON); - await runExtractYAMLTests2(extractYAMLOrJSON); - await runExtractJSONTests(extractYAMLOrJSON); + await runExtractYamlTests1(extractYamlOrJson); + await runExtractYamlTests2(extractYamlOrJson); + await runExtractJsonTests(extractYamlOrJson); }); Deno.test("createExtractor() parses any input", async () => { - await runExtractYAMLTests1(extractAny); - await runExtractYAMLTests2(extractAny); - await runExtractJSONTests(extractAny); - await runExtractTOMLTests(extractAny); + await runExtractYamlTests1(extractAny); + await runExtractYamlTests2(extractAny); + await runExtractJsonTests(extractAny); + await runExtractTomlTests(extractAny); }); diff --git a/front_matter/json.ts b/front_matter/json.ts index c841918ea..8e3630421 100644 --- a/front_matter/json.ts +++ b/front_matter/json.ts @@ -10,9 +10,10 @@ import { * Extracts and parses {@link https://www.json.org/ | JSON } from the metadata * of front matter content. * - * @example + * @example Extract JSON front matter * ```ts * import { extract } from "@std/front-matter/json"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const output = `---json * { @@ -22,9 +23,11 @@ import { * Hello, world!`; * const result = extract(output); * - * result.frontMatter; // '{\n "title": "Three dashes marks the spot"\n}' - * result.body; // "Hello, world!" - * result.attrs; // { title: "Three dashes marks the spot" } + * assertEquals(result, { + * frontMatter: '{\n "title": "Three dashes marks the spot"\n}', + * body: "Hello, world!", + * attrs: { title: "Three dashes marks the spot" }, + * }); * ``` */ export const extract: Extractor = createExtractor({ diff --git a/front_matter/json_test.ts b/front_matter/json_test.ts index 23966466b..b7cf48af4 100644 --- a/front_matter/json_test.ts +++ b/front_matter/json_test.ts @@ -3,7 +3,7 @@ import { test } from "./test.ts"; import { extract } from "./json.ts"; import { - runExtractJSONTests, + runExtractJsonTests, runExtractTypeErrorTests, runTestInvalidInputTests, runTestValidInputTests, @@ -22,5 +22,5 @@ Deno.test("json() extracts type error on invalid input", () => { }); Deno.test("json() parses json delineate by ---json", async () => { - await runExtractJSONTests(extract); + await runExtractJsonTests(extract); }); diff --git a/front_matter/mod.ts b/front_matter/mod.ts index f075478b3..e67241c15 100644 --- a/front_matter/mod.ts +++ b/front_matter/mod.ts @@ -1,4 +1,3 @@ -// deno-lint-ignore-file no-unused-vars // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. // Copyright (c) Jason Campbell. MIT license @@ -25,7 +24,8 @@ * result.attrs; // { and: "this" } * ``` * - * {@linkcode extractJson | extract} and {@linkcode test} support the following delimiters. + * {@linkcode extractJson | extract} and {@linkcode test} support the following + * delimiters. * * ```markdown * ---json @@ -56,7 +56,8 @@ * result.attrs; // { module: "front_matter" } * ``` * - * {@linkcode extractToml | extract} and {@linkcode test} support the following delimiters. + * {@linkcode extractToml | extract} and {@linkcode test} support the following + * delimiters. * * ```markdown * ---toml @@ -93,7 +94,8 @@ * result.attrs; // { module: "front_matter" } * ``` * - * {@linkcode extractYaml | extract} and {@linkcode test} support the following delimiters. + * {@linkcode extractYaml | extract} and {@linkcode test} support the following + * delimiters. * * ```front_matter * --- @@ -115,9 +117,11 @@ * * @module */ -import type { extract as extractJson } from "./json.ts"; -import type { extract as extractToml } from "./toml.ts"; -import type { extract as extractYaml } from "./yaml.ts"; +import { extract as extractJson } from "./json.ts"; +import { extract as extractToml } from "./toml.ts"; +import { extract as extractYaml } from "./yaml.ts"; export * from "./create_extractor.ts"; export * from "./test.ts"; + +export { extractJson, extractToml, extractYaml }; diff --git a/front_matter/test.ts b/front_matter/test.ts index c445e5400..836672997 100644 --- a/front_matter/test.ts +++ b/front_matter/test.ts @@ -1,22 +1,69 @@ // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. import { EXTRACT_REGEXP_MAP } from "./_formats.ts"; +import type { Format } from "./_types.ts"; -export type Format = "yaml" | "toml" | "json" | "unknown"; +export type { Format }; /** - * Tests if a string has valid front matter. Supports YAML, TOML and JSON. + * Tests if a string has valid front matter. + * Supports {@link https://yaml.org | YAML}, {@link https://toml.io | TOML} and + * {@link https://www.json.org/ | JSON}. * * @param str String to test. * @param formats A list of formats to test for. Defaults to all supported formats. + * @returns `true` if the string has valid front matter, otherwise `false`. * + * @example Test for valid YAML front matter * ```ts * import { test } from "@std/front-matter/test"; + * import { assert } from "@std/assert/assert"; * - * test("---\ntitle: Three dashes marks the spot\n---\n"); // true - * test("---toml\ntitle = 'Three dashes followed by format marks the spot'\n---\n"); // true - * test("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\n"); // true - * test("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\n", ["yaml"]); // false + * const result = test( + * `--- + * title: Three dashes marks the spot + * --- + * `); + * assert(result); + * ``` + * + * @example Test for valid TOML front matter + * ```ts + * import { test } from "@std/front-matter/test"; + * import { assert } from "@std/assert/assert"; + * + * const result = test( + * `---toml + * title = 'Three dashes followed by format marks the spot' + * --- + * `); + * assert(result); + * ``` + * + * @example Test for valid JSON front matter + * ```ts + * import { test } from "@std/front-matter/test"; + * import { assert } from "@std/assert/assert"; + * + * const result = test( + * `---json + * {"title": "Three dashes followed by format marks the spot"} + * --- + * `); + * assert(result); + * ``` + * + * @example JSON front matter is not valid as YAML + * ```ts + * import { test } from "@std/front-matter/test"; + * import { assertFalse } from "@std/assert/assert-false"; + * + * const result = test( + * `---json + * {"title": "Three dashes followed by format marks the spot"} + * --- + * `, ["yaml"]); + * assertFalse(result); * ``` */ export function test( diff --git a/front_matter/toml.ts b/front_matter/toml.ts index eacd73937..a2a4f9dcf 100644 --- a/front_matter/toml.ts +++ b/front_matter/toml.ts @@ -11,9 +11,10 @@ import { parse } from "@std/toml/parse"; * Extracts and parses {@link https://toml.io | TOML} from the metadata of * front matter content. * - * @example + * @example Extract TOML front matter * ```ts * import { extract } from "@std/front-matter/toml"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const output = `---toml * title = "Three dashes marks the spot" @@ -21,9 +22,11 @@ import { parse } from "@std/toml/parse"; * Hello, world!`; * const result = extract(output); * - * result.frontMatter; // 'title = "Three dashes marks the spot"' - * result.body; // "Hello, world!" - * result.attrs; // { title: "Three dashes marks the spot" } + * assertEquals(result, { + * frontMatter: 'title = "Three dashes marks the spot"', + * body: "Hello, world!", + * attrs: { title: "Three dashes marks the spot" }, + * }); * ``` */ export const extract: Extractor = createExtractor({ diff --git a/front_matter/toml_test.ts b/front_matter/toml_test.ts index 231730e62..196f34d1e 100644 --- a/front_matter/toml_test.ts +++ b/front_matter/toml_test.ts @@ -3,8 +3,8 @@ import { test } from "./test.ts"; import { extract } from "./toml.ts"; import { - runExtractTOMLTests, - runExtractTOMLTests2, + runExtractTomlTests, + runExtractTomlTests2, runExtractTypeErrorTests, runTestInvalidInputTests, runTestValidInputTests, @@ -23,9 +23,9 @@ Deno.test("toml() extracts type error on invalid input", () => { }); Deno.test("toml() parses toml delineate by ---toml", async () => { - await runExtractTOMLTests(extract); + await runExtractTomlTests(extract); }); Deno.test("toml() parses toml delineate by +++", async () => { - await runExtractTOMLTests2(extract); + await runExtractTomlTests2(extract); }); diff --git a/front_matter/yaml.ts b/front_matter/yaml.ts index 0fd02564a..95b2e295e 100644 --- a/front_matter/yaml.ts +++ b/front_matter/yaml.ts @@ -11,9 +11,10 @@ import { parse } from "@std/yaml/parse"; * Extracts and parses {@link https://yaml.org | YAML} from the metadata of * front matter content. * - * @example + * @example Extract YAML front matter * ```ts * import { extract } from "@std/front-matter/yaml"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const output = `---yaml * title: Three dashes marks the spot @@ -21,9 +22,11 @@ import { parse } from "@std/yaml/parse"; * Hello, world!`; * const result = extract(output); * - * result.frontMatter; // 'title: Three dashes marks the spot' - * result.body; // "Hello, world!" - * result.attrs; // { title: "Three dashes marks the spot" } + * assertEquals(result, { + * frontMatter: "title: Three dashes marks the spot", + * body: "Hello, world!", + * attrs: { title: "Three dashes marks the spot" }, + * }); * ``` */ export const extract: Extractor = createExtractor({ diff --git a/front_matter/yaml_test.ts b/front_matter/yaml_test.ts index b78cbbde2..7128fa675 100644 --- a/front_matter/yaml_test.ts +++ b/front_matter/yaml_test.ts @@ -4,8 +4,8 @@ import { test } from "./test.ts"; import { extract } from "./yaml.ts"; import { runExtractTypeErrorTests, - runExtractYAMLTests1, - runExtractYAMLTests2, + runExtractYamlTests1, + runExtractYamlTests2, runTestInvalidInputTests, runTestValidInputTests, } from "./_test_utils.ts"; @@ -23,9 +23,9 @@ Deno.test("yaml() extracts type error on invalid input", () => { }); Deno.test("yaml() parses yaml delineate by `---`", async () => { - await runExtractYAMLTests1(extract); + await runExtractYamlTests1(extract); }); Deno.test("yaml() parses yaml delineate by `---yaml`", async () => { - await runExtractYAMLTests2(extract); + await runExtractYamlTests2(extract); });