Script to keep README in sync with JSDoc

.github/workflows/node.js.yml

@@ -27,3 +27,4 @@ jobs:
           echo ::add-matcher::.github/eslint.json
           yarn run eslint . --format=compact
       - run: yarn test
+      - run: yarn readme:check

package.json

@@ -26,10 +26,12 @@
     "src/**/*.js"
   ],
   "scripts": {
-    "test": "yarn test:typecheck && yarn test:lint && yarn test:mocha",
+    "test": "yarn test:typecheck && yarn test:lint && yarn readme:check && yarn test:mocha",
     "test:mocha": "mkdir -p test/output && mocha --conditions=mocha 'test/**/*-test.*' 'test/plot.js'",
     "test:lint": "eslint src test",
     "test:typecheck": "tsc --noEmit",
+    "readme:check": "tsx scripts/jsdoc-to-readme.ts --check",
+    "readme:update": "tsx scripts/jsdoc-to-readme.ts",
     "prepublishOnly": "rm -rf dist && rollup -c && tsc",
     "postpublish": "git push && git push --tags",
     "dev": "vite"
@@ -63,7 +65,9 @@
     "prettier": "^2.7.1",
     "rollup": "2",
     "rollup-plugin-terser": "7",
+    "ts-morph": "^15.1.0",
     "tslib": "^2.4.0",
+    "tsx": "^3.8.0",
     "typescript": "^4.6.4",
     "typescript-module-alias": "^1.0.2",
     "vite": "3"

scripts/jsdoc-to-readme.ts

@@ -0,0 +1,119 @@
+import {readFileSync, writeFileSync} from "fs";
+import type {ExportedDeclarations, FunctionDeclaration} from "ts-morph";
+import {Project} from "ts-morph";
+
+/**
+ * This script will find html comments in the README of the below shape and
+ * inject the corresponding JSDoc from that exported symbol.
+ *
+ * <!-- jsdoc column -->
+ * <!-- jsdocEnd -->
+ */
+
+const readmePath = "README.md";
+let indexPath = "src/index.js";
+const project = new Project({tsConfigFilePath: "tsconfig.json"});
+
+let index = project.getSourceFile(indexPath);
+if (!index) {
+  indexPath = "src/index.ts";
+  index = project.getSourceFile(indexPath);
+  if (!index) throw new Error(`index file not found in src/`);
+}
+
+const exported = index.getExportedDeclarations();
+function getByApiName(name: string) {
+  for (const [exportedName, declarations] of exported) {
+    if (name === exportedName) {
+      return declarations[0];
+    }
+  }
+}
+
+function injectJsDoc(readme: string) {
+  const lines = readme.split("\n");
+  const output: string[] = [];
+  let insideReplacement = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    let replacement = "";
+    let isReplacementDelimiter = false;
+    if (line.startsWith("<!-- jsdocEnd")) {
+      if (!insideReplacement) throw new Error(`Unexpected jsdocEnd on line ${i}.`);
+      isReplacementDelimiter = true;
+      insideReplacement = false;
+    } else if (line.startsWith("<!-- jsdoc ")) {
+      isReplacementDelimiter = true;
+      insideReplacement = true;
+      const parts = [""];
+      const match = line.match(/jsdoc\s+(#+)?\s?(.+)\s/);
+      if (!match || match.length < 2) throw new Error(`Malformed jsdoc comment in README.md on line ${i}.`);
+      const [, prefix, name] = match;
+      const declaration = getByApiName(name);
+      if (!declaration) throw new Error(`${name} is not exported by src/index`);
+      parts.push(getJsDocs(name, declaration, prefix));
+      parts.push("");
+      replacement = parts.join("\n");
+    }
+    if (!insideReplacement || isReplacementDelimiter) output.push(line);
+    if (replacement) output.push(replacement);
+  }
+  return output.join("\n");
+}
+
+function getJsDocs(name: string, declaration: ExportedDeclarations, prefix = "####") {
+  if ("getParameters" in declaration) {
+    return getJsDocsForFunction(name, declaration, prefix);
+  }
+  if ("getJsDocs" in declaration) {
+    return `${prefix} Plot.${name}\n${declaration
+      .getJsDocs()
+      .map((doc) => makeRelativeUrls(doc.getDescription()))
+      .join("\n\n")}`;
+  }
+  return `JSDoc extraction for ${declaration.getKindName()} not yet implemented.`;
+}
+
+function getJsDocsForFunction(name: string, declaration: FunctionDeclaration, prefix = "####") {
+  const parameters = declaration.getParameters();
+  const title = `${prefix} Plot.${name}(${parameters
+    .map((param) => `${param.getDotDotDotToken() ? "..." : ""}*${param.getName()}*`)
+    .join(", ")})`;
+  const parts = [title];
+  const docs = declaration.getJsDocs();
+  if (docs.length) {
+    parts.push(docs.map((doc) => makeRelativeUrls(doc.getDescription())).join("\n\n"));
+    return parts.join("\n");
+  }
+  // If we didn't find docs on the implementation, it's probably on one of the
+  // overloads.
+  const overloads = declaration.getOverloads();
+  for (const overload of overloads) {
+    const docs = overload.getJsDocs();
+    if (!docs.length) continue;
+    parts.push(docs.map((doc) => makeRelativeUrls(doc.getDescription())).join("\n\n"));
+    return parts.join("\n");
+  }
+
+  return "No JSDocs found.";
+}
+
+function makeRelativeUrls(description: string) {
+  return description.replace(new RegExp("https://github.com/observablehq/plot/blob/main/README.md#", "g"), "#");
+}
+
+const check = process.argv[process.argv.length - 1] === "--check";
+const original = readFileSync(readmePath, {encoding: "utf-8"});
+const output = injectJsDoc(original);
+
+if (original !== output) {
+  if (check) {
+    console.log("README.md is out of sync. Please run `yarn readme:update`");
+    process.exit(1);
+  } else {
+    writeFileSync(readmePath, output);
+    console.log("README.md has been updated based on the JSDoc annotations.");
+  }
+} else {
+  console.log("README.md requires no changes.");
+}

src/format.ts

@@ -20,21 +20,54 @@ export function formatNumber(locale = "en-US"): (value: any) => string | undefin
   return (i: any) => (i != null && !isNaN(i) ? format.format(i) : undefined);
 }
 
+/**
+ * ```js
+ * Plot.formatMonth("es-MX", "long")(0) // "enero"
+ * ```
+ *
+ * Returns a function that formats a given month number (from 0 = January to 11
+ * = December) according to the specified *locale* and *format*. The *locale* is
+ * a [BCP 47 language tag](https://tools.ietf.org/html/bcp47) and defaults to
+ * U.S. English. The *format* is a [month
+ * format](https://tc39.es/ecma402/#datetimeformat-objects): either *2-digit*,
+ * *numeric*, *narrow*, *short*, *long*; if not specified, it defaults to
+ * *short*.
+ */
 export function formatMonth(
   locale = "en-US",
-  month: "numeric" | "2-digit" | "long" | "short" | "narrow" | undefined = "short"
+  format: "numeric" | "2-digit" | "long" | "short" | "narrow" | undefined = "short"
 ) {
-  const format = monthFormat(locale, month);
+  const fmt = monthFormat(locale, format);
   return (i: Date | number | null | undefined) =>
-    i != null && !isNaN((i = +new Date(Date.UTC(2000, +i)))) ? format.format(i) : undefined;
+    i != null && !isNaN((i = +new Date(Date.UTC(2000, +i)))) ? fmt.format(i) : undefined;
 }
 
-export function formatWeekday(locale = "en-US", weekday: "long" | "short" | "narrow" | undefined = "short") {
-  const format = weekdayFormat(locale, weekday);
+/**
+ * ```js
+ * Plot.formatWeekday("es-MX", "long")(0) // "domingo"
+ * ```
+ *
+ * Returns a function that formats a given week day number (from 0 = Sunday to 6
+ * = Saturday) according to the specified *locale* and *format*. The *locale* is
+ * a [BCP 47 language tag](https://tools.ietf.org/html/bcp47) and defaults to
+ * U.S. English. The *format* is a [weekday
+ * format](https://tc39.es/ecma402/#datetimeformat-objects): either *narrow*,
+ * *short*, or *long*; if not specified, it defaults to *short*.
+ */
+export function formatWeekday(locale = "en-US", format: "long" | "short" | "narrow" | undefined = "short") {
+  const fmt = weekdayFormat(locale, format);
   return (i: Date | number | null | undefined) =>
-    i != null && !isNaN((i = +new Date(Date.UTC(2001, 0, +i)))) ? format.format(i) : undefined;
+    i != null && !isNaN((i = +new Date(Date.UTC(2001, 0, +i)))) ? fmt.format(i) : undefined;
 }
 
+/**
+ * ```js
+ * Plot.formatIsoDate(new Date("2020-01-01T00:00.000Z")) // "2020-01-01"
+ * ```
+ *
+ * Given a *date*, returns the shortest equivalent ISO 8601 UTC string. If the
+ * given *date* is not valid, returns `"Invalid Date"`.
+ */
 export function formatIsoDate(date: Date): string {
   return isoFormat(date, "Invalid Date");
 }

src/legends.js

@@ -11,6 +11,30 @@ const legendRegistry = new Map([
   ["opacity", legendOpacity]
 ]);
 
+/**
+ * Returns a standalone legend for the scale defined by the given *options*
+ * object. The *options* object must define at least one scale; see [Scale
+ * options](https://github.com/observablehq/plot/blob/main/README.md#scale-options)
+ * for how to define a scale. For example, here is a ramp legend of a linear
+ * color scale with the default domain of [0, 1] and default scheme *turbo*:
+ *
+ * ```js
+ * Plot.legend({color: {type: "linear"}})
+ * ```
+ *
+ * The *options* object may also include any additional legend options described
+ * in the previous section. For example, to make the above legend slightly
+ * wider:
+ *
+ * ```js
+ * Plot.legend({
+ *   width: 320,
+ *   color: {
+ *     type: "linear"
+ *   }
+ * })
+ * ```
+ */
 export function legend(options = {}) {
   for (const [key, value] of legendRegistry) {
     const scale = options[key];

src/marks/area.js

@@ -71,16 +71,93 @@ export class Area extends Mark {
   }
 }
 
+/**
+ * ```js
+ * Plot.area(aapl, {x1: "Date", y1: 0, y2: "Close"})
+ * ```
+ *
+ * Returns a new area with the given *data* and *options*. Plot.area is rarely
+ * used directly; it is only needed when the baseline and topline have neither
+ * common *x* nor *y* values.
+ * [Plot.areaY](https://github.com/observablehq/plot/blob/main/README.md#plotareaydata-options)
+ * is used in the common horizontal orientation where the baseline and topline
+ * share *x* values, while
+ * [Plot.areaX](https://github.com/observablehq/plot/blob/main/README.md#plotareaxdata-options)
+ * is used in the vertical orientation where the baseline and topline share *y*
+ * values.
+ */
 export function area(data, options) {
   if (options === undefined) return areaY(data, {x: first, y: second});
   return new Area(data, options);
 }
 
+/**
+ * ```js
+ * Plot.areaX(aapl, {y: "Date", x: "Close"})
+ * ```
+ *
+ * Returns a new area with the given *data* and *options*. This constructor is
+ * used when the baseline and topline share *y* values, as in a time-series area
+ * chart where time goes up↑. If neither the **x1** nor **x2** option is
+ * specified, the **x** option may be specified as shorthand to apply an
+ * implicit [stackX
+ * transform](https://github.com/observablehq/plot/blob/main/README.md#plotstackxstack-options);
+ * this is the typical configuration for an area chart with a baseline at *x* =
+ * 0. If the **x** option is not specified, it defaults to the identity
+ * function. The **y** option specifies the **y1** channel; and the **y1** and
+ * **y2** options are ignored.
+ *
+ * If the **interval** option is specified, the [binY
+ * transform](https://github.com/observablehq/plot/blob/main/README.md#bin) is
+ * implicitly applied to the specified *options*. The reducer of the output *x*
+ * channel may be specified via the **reduce** option, which defaults to
+ * *first*. To default to zero instead of showing gaps in data, as when the
+ * observed value represents a quantity, use the *sum* reducer.
+ *
+ * ```js
+ * Plot.areaX(observations, {y: "date", x: "temperature", interval: d3.utcDay})
+ * ```
+ *
+ * The **interval** option is recommended to “regularize” sampled data; for
+ * example, if your data represents timestamped temperature measurements and you
+ * expect one sample per day, use d3.utcDay as the interval.
+ */
 export function areaX(data, options) {
   const {y = indexOf, ...rest} = maybeDenseIntervalY(options);
   return new Area(data, maybeStackX(maybeIdentityX({...rest, y1: y, y2: undefined})));
 }
 
+/**
+ * ```js
+ * Plot.areaY(aapl, {x: "Date", y: "Close"})
+ * ```
+ *
+ * Returns a new area with the given *data* and *options*. This constructor is
+ * used when the baseline and topline share *x* values, as in a time-series area
+ * chart where time goes right→. If neither the **y1** nor **y2** option is
+ * specified, the **y** option may be specified as shorthand to apply an
+ * implicit [stackY
+ * transform](https://github.com/observablehq/plot/blob/main/README.md#plotstackystack-options);
+ * this is the typical configuration for an area chart with a baseline at *y* =
+ * 0. If the **y** option is not specified, it defaults to the identity
+ * function. The **x** option specifies the **x1** channel; and the **x1** and
+ * **x2** options are ignored.
+ *
+ * If the **interval** option is specified, the [binX
+ * transform](https://github.com/observablehq/plot/blob/main/README.md#bin) is
+ * implicitly applied to the specified *options*. The reducer of the output *y*
+ * channel may be specified via the **reduce** option, which defaults to
+ * *first*. To default to zero instead of showing gaps in data, as when the
+ * observed value represents a quantity, use the *sum* reducer.
+ *
+ * ```js
+ * Plot.areaY(observations, {x: "date", y: "temperature", interval: d3.utcDay)
+ * ```
+ *
+ * The **interval** option is recommended to “regularize” sampled data; for
+ * example, if your data represents timestamped temperature measurements and you
+ * expect one sample per day, use d3.utcDay as the interval.
+ */
 export function areaY(data, options) {
   const {x = indexOf, ...rest} = maybeDenseIntervalX(options);
   return new Area(data, maybeStackY(maybeIdentityY({...rest, x1: x, x2: undefined})));

src/marks/arrow.js

@@ -176,8 +176,16 @@ function circleCircleIntersect([ax, ay, ar], [bx, by, br], sign) {
   return [ax + (dx * x + dy * y) / d, ay + (dy * x - dx * y) / d];
 }
 
-export function arrow(data, {x, x1, x2, y, y1, y2, ...options} = {}) {
+/**
+ * ```js
+ * Plot.arrow(inequality, {x1: "POP_1980", y1: "R90_10_1980", x2: "POP_2015", y2: "R90_10_2015", bend: true})
+ * ```
+ *
+ * Returns a new arrow with the given *data* and *options*.
+ */
+export function arrow(data, options = {}) {
+  let {x, x1, x2, y, y1, y2, ...remainingOptions} = options;
   [x1, x2] = maybeSameValue(x, x1, x2);
   [y1, y2] = maybeSameValue(y, y1, y2);
-  return new Arrow(data, {...options, x1, x2, y1, y2});
+  return new Arrow(data, {...remainingOptions, x1, x2, y1, y2});
 }