tools: overhaul tools/doc/json.js

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• commit message follows commit guidelines

Sorry for the big diff. The script seems rather old and I've decided to not create dozens of PRs for all these nits. Some changes are obvious, a few need some delving, but I can explain the unclear bits.

I just wanted that someone after me would scratch their head over this script not so long)

Here is a concise summary of all changes.

Modernize:

• Replace var with const / let.
• Wrap switch cases with const/let in blocks.
• Replace common functions with arrow functions.
• Replace string concatenation with template literals.
• Shorthand object literals.
• Use destructuring and spread.

Optimize:

• Move RegExp declaration out of loops.
• Replace .match() with .test() in boolean context.
• Replace RegExp with string when string suffices.
• Make RegExp more strict to reject unrelated cases.
• Make RegExp do the trimming to eliminate many .trim() calls.
• Cache retrieved object properties.
• Remove conditions that cannot be false.
• Remove code that seems obsolete (it means a state that cannot happen or is not typical).

Clarify:

• Sync code examples in comments with the actual source state.
• Expand some one-letter variable names.
• Rename confusingly similar variables.
• Move variable declarations closer to their context.
• Remove non-actual commented out code.
• Unify blank lines between top-level blocks.

Fix:

• Fix conditions that cannot be true.

Guard:

• Throw on unexpected state more often.