Skip to content

tools: simplify tools/doc/preprocess.js

Rodrigo Muino Tomonari requested to merge github/fork/vsemozhetbyt/tools-doc-preprocess-simplify into master
Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • commit message follows commit guidelines

This PR seems to be a big refactoring, but it is rather simple and trims the script down almost by half, streamlining the logic significantly.

Investigated status quo in preprocess.js

tools/doc/preprocess.js seems to either contain artifacts from some very old doc system state or to be designed for a much more complicated doc system than the current one, just in case.

  1. preprocess.js has two aims: strip @// comments in doc sources + replace @include directives with outer file content.
  2. preprocess.js is designed to support repeated @include directives so it uses caching.
  3. preprocess.js is designed to support nested @include directives so it calls its main exported function recursively.
  4. preprocess.js is designed to support docs with various file extensions (.md, .markdown, etc).

Investigated status quo in doc building system and doc sources

  1. Only included doc/api/_toc.md has @// comments .
  2. Only doc/api/index.md and doc/api/all.md have @include directives. None of these cases has repeated or nested directives, so neither caching nor recursive processing is needed here.
  3. Our docs have only .md extension.
  4. Except for the main use in tools/doc/generate.js, preprocess.js is also used in tools/doc/html.js and test/doctool/test-doctool-html.js. Neither of these cases means repeated or nested directives as well.
  5. The only cause for recursive calls is comment stripping in main and included docs. This is a very simple operation needed only for one included doc, so it can be inlined (for both main and included docs to be on the safe side for future comment additions).

Simplification strategy

  1. Remove caching.
  2. Remove recursion.
  3. Remove auxiliary functions and export the single remaining function.
  4. Inline comment stripping.
  5. Expect only .md file extension.

I've built the docs on Windows (using https://github.com/nodejs/node/issues/19330) before and after these changes and both doc sets are identical + doctool tests are OK.

Merge request reports