Intertwined JavaScript + Markdown Parsing #530

Ref: #402
Ref: #441
Ref: #214
Ref: #287
Ref: #354

The Node.js documentation has become increasingly complex as the contributor-base has grown. Today, due to the diverse number of authors, the documentation is full of little inconsistent formats and structures across documentation files. Parsing these varied formats (especially lists) has proven to be quite the challenge.

However, if we integrate JSDoc parsing with markdown parsing, we can leverage JSDoc for metadata, parameter typings, and function signatures. The Markdown docs would be mostly reserved for free-form documentation + YAML metadata.

In the event a function does not have the proper JSDoc, we fall back to the Markdown (since, if this is even something we consider, it'll take a while to add JSDoc to core)

Given the following inputs:

### `fs.mkdirSync` <!-- Note: The header here has no parameters, as those are populated from the signatures -->

<!-- YAML
added: v0.1.21
changes:
  - ... 
-->

Description... 

/**
 * @param {string|Buffer|URL} path The file path
 */
function mkdirSync(path) {
  ... 
}

The parser/generator will be able to generate metadata with all the signatures, parameters, and their appropriate descriptions.

In a case where a sub-list is needed, using - to indicate a list item in the JSDoc can be used.

/**
 * @param {"one"|"two"|"three"} mode The operation mode: 
 *   - "one": do X
 *   - "two": do Y
 *   - "three": do Z
 **/

In a case where a function has multiple unique signatures, the @overload property can be used:

/**
 * @overload
 * @param {string} path
 * @param {Object} options
 * @returns {string}
 *
 * @overload
 * @param {Buffer} path
 * @returns {undefined}
 */

Each overload will generate a unique header, but only one header should exist in the markdown file.

This'll tie in well to #441, since the types used in JSDoc will be valid TypeScript types, making it extremely easy for consumers. Additionally, it follows the similar format used in the json generator prototype (#287), as that follows JSDoc syntax.

Obviously, this is a long-term goal, and not something that we can achieve until after the new tooling lands, and core is properly typed (and that's a huge undertaking within itself)

How we would implement this

Currently, we are in "Phase 1":

0. Legacy tooling generating a legacy page from legacy markdown
1. New tooling generating a legacy page from legacy markdown
2. New tooling generating a new page from legacy markdown
3. New tooling generating a new page from new markdown ("new" being the intertwined version)
   1. JSDoc needs to be implemented throughout core
   2. A new generator chain [*.js, *.md] -> intertwined-metadata needs to be created
   3. The jsx-ast generator needs to be updated to accept this new metadata format