tools: simplify tools/doc/preprocess.js
Checklist
-
make -j4 test
(UNIX), orvcbuild 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.
preprocess.js
Investigated status quo in 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.
-
preprocess.js
has two aims: strip@//
comments in doc sources + replace@include
directives with outer file content. -
preprocess.js
is designed to support repeated@include
directives so it uses caching. -
preprocess.js
is designed to support nested@include
directives so it calls its main exported function recursively. -
preprocess.js
is designed to support docs with various file extensions (.md
,.markdown
, etc).
Investigated status quo in doc building system and doc sources
- Only included
doc/api/_toc.md
has@//
comments . - Only
doc/api/index.md
anddoc/api/all.md
have@include
directives. None of these cases has repeated or nested directives, so neither caching nor recursive processing is needed here. - Our docs have only
.md
extension. - Except for the main use in
tools/doc/generate.js
,preprocess.js
is also used intools/doc/html.js
andtest/doctool/test-doctool-html.js
. Neither of these cases means repeated or nested directives as well. - 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
- Remove caching.
- Remove recursion.
- Remove auxiliary functions and export the single remaining function.
- Inline comment stripping.
- 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.