Skip to content

tools: overhaul tools/doc/html.js

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

I was trying to facilitate reviewing this PR as far as I could, singling out changes that refactor monolithic structures or alter doc results (see #20307, #20514, #20552, #20586).

However, this PR still produces big and complicated diff as it has many small changes scattered all over the script and also bears refactoring (simplifying, merging, inlining etc) closely coupled but tracery systems. It would be hard to split these changes into dozens of separate PRs.

To make review even possible, I've split it into 2 commits: local changes + pure reordering of major blocks with no additions/deletions. Please, review these commits separately.

commit 1

  • Modernize:

    • Replace var with const / let.
    • Replace common functions with arrow functions.
    • Use destructuring.
    • Shorthand object literals.

  • Optimize:

    • Reduce global variables.
    • Reduce intermediate structures, variables or assignments.
    • Reduce function calls.
    • Inline small one-off functions (sometimes removing wrong abstractions).
    • Join functions with similar purpose (as toHTML() and render()) to reduce data transferring.
    • Remove conditions that cannot be false.
    • Simplify RegExps.
    • Move RegExp declarations out of hot functions.
    • Replace RegExp with string when string suffices, use .includes().
    • Replace .match() with .test() in boolean context.
    • Replace ['str', 'str'].join() with straight string concatenation.
    • Replace new Array(length + 1).join(str) with str.repeat(length).
    • Replace loops with appropriate array methods.
    • De-callbackify synchronous function chains.

  • Clarify:

    • Correct comments.
    • Sync comments with the actual source state.
    • Remove redundant or obsolete comments.
    • Expand some one/two-letters variable names.
    • Rename confusingly similar variables.
    • Rename functions to define their aim more correctly.

Commit 2

  • Reorder function declarations chronologically (in order of calls) to make reading script code easier.

This PR produces HTML docs identical to the previous ones, reducing the script by ~ 100 lines (with previous 4 PRs, the size is reduced by 175 lines) and I hope the script becomes a bit clearer and simpler.

Merge request reports