copy jsdocs from README to code

Author: mbostock

.gitignore

@@ -1,4 +1,5 @@
 .DS_Store
+build/
 dist/
 types/
 node_modules/

README.md

@@ -28,13 +28,11 @@
     "types/**/*.d.ts"
   ],
   "scripts": {
-    "test": "yarn test:mocha && yarn test:typecheck && yarn test:lint && yarn readme:check",
+    "test": "yarn test:mocha && yarn test:typecheck && yarn test:lint",
     "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",
+    "prepublishOnly": "rm -rf build dist && rollup -c && tsc && tsx scripts/readme-to-jsdoc.ts",
     "postpublish": "git push && git push --tags",
     "dev": "vite"
   },
@@ -62,13 +60,12 @@
     "htl": "0.3",
     "js-beautify": "1",
     "jsdom": "19",
+    "mkdirp": "^1.0.4",
     "mocha": "10",
     "module-alias": "2",
     "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",

package.json

@@ -38,7 +38,7 @@ export default [
       name: "Plot",
       format: "umd",
       extend: true,
-      file: `dist/${filename}.umd.js`,
+      file: `build/${filename}.umd.js`,
       globals: {d3: "d3"},
       paths: {d3: d3Path}
     }

rollup.config.js

@@ -0,0 +1,84 @@
+import {readFileSync, writeFileSync} from "fs";
+import {dirname} from "path";
+import glob from "glob";
+import mkdirp from "mkdirp";
+
+// Extract the documentation from the README.
+const readme = readFileSync("./README.md", "utf-8");
+const docmap = new Map<string, string[]>();
+let doc: {name: string; lines: string[]} | null = null;
+for (const [i, line] of readme.split("\n").entries()) {
+  if (/<!--\s*jsdoc/.test(line)) {
+    let match: RegExpExecArray | null;
+    if ((match = /^<!--\s+jsdoc\s+(\w+)\s+-->$/.exec(line))) {
+      const [, name] = match;
+      if (doc) {
+        throw new Error(`nested jsdoc directive on line ${i}: ${line}`);
+      }
+      if (docmap.has(name)) {
+        throw new Error(`duplicate jsdoc directive on line ${i}: ${line}`);
+      }
+      doc = {name, lines: []};
+    } else if ((match = /^<!--\s+jsdocEnd\s+(\w+)\s+-->$/.exec(line))) {
+      const [, name] = match;
+      if (!doc) {
+        throw new Error(`orphaned jsdocEnd directive on line ${i}: ${line}`);
+      }
+      if (doc.name !== name) {
+        throw new Error(`mismatched jsdocEnd ${doc.name} directive on line ${i}: ${line}`);
+      }
+      docmap.set(doc.name, doc.lines);
+      doc = null;
+    } else {
+      throw new Error(`malformed jsdoc directive on line ${i}: ${line}`);
+    }
+  } else if (doc) {
+    doc.lines.push(line);
+  }
+}
+
+// Make relative and anchor links absolute.
+for (const lines of docmap.values()) {
+  for (let i = 0, n = lines.length; i < n; ++i) {
+    const iline = lines[i];
+    const oline = iline
+      .replace(/\]\(#([^)]+)\)/g, "](./README.md#$1)")
+      .replace(/\]\(\.\/([^)]+)\)/g, "](https://github.com/observablehq/plot/blob/main/$1)");
+    if (iline !== oline) {
+      process.stdout.write(`\x1b[2m${iline}\x1b[0m → \x1b[36m${oline}\x1b[0m\n`);
+      process.exit(1);
+    }
+  }
+}
+
+// Copy files from build/ to dist/, replacing /** @jsdoc name */ directives.
+const unused = new Set(docmap.keys());
+for (const file of glob.sync("build/**/*.js")) {
+  process.stdout.write(`\x1b[2m${file}\x1b[0m`);
+  const lines = readFileSync(file, "utf-8").split("\n");
+  let count = 0;
+  for (let i = 0, n = lines.length; i < n; ++i) {
+    let match: RegExpExecArray | null;
+    if ((match = /^\/\*\*\s+@jsdoc\s+(\w+)\s+\*\/$/.exec(lines[i]))) {
+      const [, name] = match;
+      const docs = docmap.get(name);
+      if (!docs) throw new Error(`missing @jsdoc definition: ${name}`);
+      if (file === "build/plot.umd.js") "ignore";
+      else if (!unused.has(name)) throw new Error(`duplicate @jsdoc reference: ${name}`);
+      else unused.delete(name);
+      ++count;
+      lines[i] = docs
+        .map((line, i, lines) => (i === 0 ? `/** ${line}` : i === lines.length - 1 ? ` * ${line}\n */` : ` * ${line}`))
+        .join("\n");
+    }
+  }
+  const ofile = file.replace(/^build\//, "dist/");
+  process.stdout.write(` → \x1b[36m${ofile}\x1b[0m${count ? ` (${count} jsdoc${count === 1 ? "" : "s"})` : ""}\n`);
+  const odir = dirname(ofile);
+  mkdirp.sync(odir);
+  writeFileSync(ofile, lines.join("\n"), "utf-8");
+}
+
+for (const name of unused) {
+  console.warn(`\x1b[33m[warning] unused @jsdoc directive:\x1b[0m ${name}`);
+}

scripts/jsdoc-to-readme.ts

@@ -20,19 +20,7 @@ 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*.
- */
+/** @jsdoc formatMonth */
 export function formatMonth(
   locale = "en-US",
   format: "numeric" | "2-digit" | "long" | "short" | "narrow" | undefined = "short"
@@ -42,32 +30,14 @@ export function formatMonth(
     i != null && !isNaN((i = +new Date(Date.UTC(2000, +i)))) ? fmt.format(i) : undefined;
 }
 
-/**
- * ```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*.
- */
+/** @jsdoc formatWeekday */
 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)))) ? 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"`.
- */
+/** @jsdoc formatIsoDate */
 export function formatIsoDate(date: Date): string {
   return isoFormat(date, "Invalid Date");
 }

scripts/readme-to-jsdoc.ts

@@ -11,30 +11,7 @@ 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"
- *   }
- * })
- * ```
- */
+/** @jsdoc legend */
 export function legend(options = {}) {
   for (const [key, value] of legendRegistry) {
     const scale = options[key];