tools: parse types into links in doc html gen

Changes the parsing of parameter types in the doc html gen
Links to either MDN or nodejs docs depending on type
See #4350

PR-URL: #4741
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Chris Dickinson <chris@neversaw.us>
Reviewed-By: Roman Reiss <me@silverwind.io>

tools/doc/html.js

@@ -4,6 +4,7 @@ var fs = require('fs');
 var marked = require('marked');
 var path = require('path');
 var preprocess = require('./preprocess.js');
+var typeParser = require('./type-parser.js');
 
 module.exports = toHTML;
 
@@ -118,7 +119,8 @@ function parseLists(input) {
       output.push({ type: 'html', text: tok.text });
       return;
     }
-    if (state === null) {
+    if (state === null ||
+      (state === 'AFTERHEADING' && tok.type === 'heading')) {
       if (tok.type === 'heading') {
         state = 'AFTERHEADING';
       }
@@ -168,9 +170,15 @@ function parseLists(input) {
 function parseListItem(text) {
   var parts = text.split('`');
   var i;
+  var typeMatches;
 
   for (i = 0; i < parts.length; i += 2) {
-    parts[i] = parts[i].replace(/\{([^\}]+)\}/, '<span class="type">$1</span>');
+    typeMatches = parts[i].match(/\{([^\}]+)\}/g);
+    if (typeMatches) {
+      typeMatches.forEach(function(typeMatch) {
+        parts[i] = parts[i].replace(typeMatch, typeParser.toLink(typeMatch));
+      });
+    }
   }
 
   //XXX maybe put more stuff here?
@@ -229,4 +237,3 @@ function getId(text) {
   }
   return text;
 }
-

tools/doc/type-parser.js

@@ -0,0 +1,59 @@
+'use strict';
+const nodeDocUrl = '';
+const jsDocUrl = 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/' +
+  'Reference/Global_Objects/';
+const jsPrimitiveUrl = 'https://developer.mozilla.org/en-US/docs/Web/' +
+  'JavaScript/Data_structures';
+const jsPrimitives = [
+  'Number', 'String', 'Boolean', 'Null', 'Symbol'
+]
+const jsGlobalTypes = [
+  'Error', 'Object', 'Function', 'Array', 'Uint8Array',
+  'Uint16Array', 'Uint32Array', 'Int8Array', 'Int16Array', 'Int32Array',
+  'Uint8ClampedArray', 'Float32Array', 'Float64Array', 'Date', 'RegExp',
+  'ArrayBuffer', 'DataView', 'Promise'
+];
+const typeMap = {
+  'Buffer': 'buffer.html#buffer_class_buffer',
+  'Handle': 'net.html#net_server_listen_handle_backlog_callback',
+  'Stream': 'stream.html#stream_stream',
+  'stream.Writable': 'stream.html#stream_class_stream_writable',
+  'stream.Readable': 'stream.html#stream_class_stream_readable',
+  'ChildProcess': 'child_process.html#child_process_class_childprocess',
+  'cluster.Worker': 'cluster.html#cluster_class_worker',
+  'dgram.Socket': 'dgram.html#dgram_class_dgram_socket',
+  'net.Socket': 'net.html#net_class_net_socket',
+  'EventEmitter': 'events.html#events_class_events_eventemitter',
+  'Timer': 'timers.html#timers_timers'
+};
+
+module.exports = {
+  toLink: function (typeInput) {
+    let typeLinks = [];
+    typeInput = typeInput.replace('{', '').replace('}', '');
+    let typeTexts = typeInput.split('|');
+
+    typeTexts.forEach(function (typeText) {
+      typeText = typeText.trim();
+      if (typeText) {
+        let typeUrl = null;
+        if (jsPrimitives.indexOf(typeText) !== -1) {
+          typeUrl = jsPrimitiveUrl + '#' + typeText + '_type';
+        } else if (jsGlobalTypes.indexOf(typeText) !== -1) {
+          typeUrl = jsDocUrl + typeText;
+        } else if (typeMap[typeText]) {
+          typeUrl = nodeDocUrl + typeMap[typeText];
+        }
+
+        if (typeUrl) {
+          typeLinks.push('<a href="' + typeUrl + '" class="type">&lt;' +
+            typeText + '&gt;</a>');
+        } else {
+          typeLinks.push('<span class="type">&lt;' + typeText + '&gt;</span>');
+        }
+      }
+    });
+
+    return typeLinks.length ? typeLinks.join(' | ') : typeInput;
+  }
+}