copy docs from README to code

[mbostock]

Rather than copy docs from source code into our README, this does the reverse, copying docs from the README into generated source files (that are not checked in). This offers several advantages:

• The docs are no longer hard-wrapped. 😌
• There’s only one copy of the docs, avoiding potential drift and errant edits.
• The README can continue to use relative links (important for versioning).
• We don’t need ts-morph or to declare a “prefix” (e.g., ##); we simply reference a given doc by name.

In addition, I added some stricter checks:

• We disallow unterminated jsdoc directives, requiring a matching jsdocEnd for each jsdoc.
• We validate jsdoc directives more strictly, catching errors such as <!-- jsdoc stack ->.
• We require each jsdoc directive in the README to be consumed exactly once in the source code.

[mbostock]

If it helps, you can review the changes to the README by diffing against the version prior to #1034

9d9ba91...mbostock/one-docs#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5

[Fil]

👍

Shouldn't we rmdir the build/ directory as the last step (as well as as the first step)? I got a bit confused at first.

[mbostock]

Shouldn't we rmdir the build/ directory as the last step (as well as as the first step)?

Usually it is typical to preserve intermediate build artifacts for debugging purposes (and for incremental rebuilds if needed).

[duaneatat]

This is nice, but perhaps we should discuss #1055 since these approaches appear to be incompatible?

[mbostock]

@duaneatat A quick addition to this approach would be to support JSDoc type delcarations like so:

/**
 * @jsdoc area
 * @param {Data} data
 * @param {Options=} options
 */

So, I don’t see this approach as being incompatible, and it would still mean there’s only one copy of everything. The type declarations would live with the code and the documentation would live in the README.

[duaneatat]

So, I don’t see this approach as being incompatible, and it would still mean there’s only one copy of everything. The type declarations would live with the code and the documentation would live in the README.

Ahh, yes that's quite nice!

[meetamit]

Heads up: When readme-to-jsdoc.ts runs on a Windows machine, unfortunately, the script throws a malformed jsdoc directive error. The cause is that readme.split("\n") leaves a \r at the end of each line, and the RegExps, which rely on $ don't match the directives. I've confirmed that modifying the split to be readme.split("\r\n") fixes the issue.

[Fil]

can you confirm is readme.split(/\r?\n/) works for you?

[meetamit]

Hi @Fil.
Yes -- that works.