tools: flatten apidoc headers

ensure optional parameters are not treated as markedown links by
replacing the children of headers nodes with a single text node
containing the raw markup;

Fixes issue identified in
#21490 (comment)

PR-URL: #21936
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Minwoo Jung <minwoo@nodesource.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

tools/doc/html.js

@@ -175,9 +175,9 @@ function linkJsTypeDocs(text) {
   return parts.join('`');
 }
 
-// Preprocess stability blockquotes and YAML blocks
+// Preprocess headers, stability blockquotes, and YAML blocks.
 function preprocessElements({ filename }) {
-  return (tree) => {
+  return (tree, file) => {
     const STABILITY_RE = /(.*:)\s*(\d)([\s\S]*)/;
     let headingIndex = -1;
     let heading = null;
@@ -187,6 +187,22 @@ function preprocessElements({ filename }) {
         headingIndex = index;
         heading = node;
 
+        // Ensure optional API parameters are not treated as links by
+        // collapsing all of heading into a single text node.
+        if (heading.children.length > 1) {
+          const position = {
+            start: heading.children[0].position.start,
+            end: heading.position.end
+          };
+
+          heading.children = [{
+            type: 'text',
+            value: file.contents.slice(
+              position.start.offset, position.end.offset),
+            position
+          }];
+        }
+
       } else if (node.type === 'html' && common.isYAMLBlock(node.value)) {
         node.value = parseYAML(node.value);
 
@@ -331,10 +347,9 @@ function buildToc({ filename }) {
 
       depth = node.depth;
       const realFilename = path.basename(realFilenames[0], '.md');
-      const headingText = node.children.map((child) =>
-        file.contents.slice(child.position.start.offset,
-                            child.position.end.offset)
-      ).join('').trim();
+      const headingText = file.contents.slice(
+        node.children[0].position.start.offset,
+        node.position.end.offset).trim();
       const id = getId(`${realFilename}_${headingText}`, idCounters);
 
       const hasStability = node.stability !== undefined;