doc, tools: make type parsing more strict

PR-URL: https://github.com/nodejs/node/pull/19881
Reviewed-By: Gus Caplan <me@gus.host>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

doc/api/addons.md

@@ -1096,8 +1096,10 @@ has ended but before the JavaScript VM is terminated and Node.js shuts down.
 
 #### void AtExit(callback, args)
 
-* `callback` {void (\*)(void\*)} A pointer to the function to call at exit.
+* `callback` <span class="type">&lt;void (\*)(void\*)&gt;</span>
-* `args` {void\*} A pointer to pass to the callback at exit.
+  A pointer to the function to call at exit.
+* `args` <span class="type">&lt;void\*&gt;</span>
+  A pointer to pass to the callback at exit.
 
 Registers exit hooks that run after the event loop has ended but before the VM
 is killed.

doc/api/deprecations.md

@@ -890,12 +890,13 @@ should start using the `async_context` variant of `MakeCallback` or
 `CallbackScope`, or the high-level `AsyncResource` class.
 
 <a id="DEP0098"></a>
-### DEP0098: AsyncHooks Embedder AsyncResource.emit{Before,After} APIs
+### DEP0098: AsyncHooks Embedder AsyncResource.emitBefore and AsyncResource.emitAfter APIs
 
 Type: Runtime
 
-The embedded API provided by AsyncHooks exposes emit{Before,After} methods
+The embedded API provided by AsyncHooks exposes `.emitBefore()` and
-which are very easy to use incorrectly which can lead to unrecoverable errors.
+`.emitAfter()` methods which are very easy to use incorrectly which can lead
+to unrecoverable errors.
 
 Use [`asyncResource.runInAsyncScope()`][] API instead which provides a much
 safer, and more convenient, alternative. See

doc/api/http2.md

@@ -2532,7 +2532,7 @@ authentication details.
 added: v8.4.0
 -->
 
-* {http2.Http2Stream}
+* {Http2Stream}
 
 The [`Http2Stream`][] object backing the request.
 
@@ -2948,7 +2948,7 @@ an empty string.
 added: v8.4.0
 -->
 
-* {http2.Http2Stream}
+* {Http2Stream}
 
 The [`Http2Stream`][] object backing the response.
 

doc/api/process.md

@@ -89,8 +89,8 @@ the child process.
 
 The listener callback is invoked with the following arguments:
 * `message` {Object} a parsed JSON object or primitive value.
-* `sendHandle` {Handle object} a [`net.Socket`][] or [`net.Server`][] object, or
+* `sendHandle` {net.Server|net.Socket} a [`net.Server`][] or [`net.Socket`][]
-  undefined.
+  object, or undefined.
 
 The message goes through serialization and parsing. The resulting message might
 not be the same as what is originally sent.
@@ -1531,7 +1531,7 @@ added: v0.5.9
 -->
 
 * `message` {Object}
-* `sendHandle` {Handle object}
+* `sendHandle` {net.Server|net.Socket}
 * `options` {Object}
 * `callback` {Function}
 * Returns: {boolean}

tools/doc/type-parser.js

@@ -2,15 +2,15 @@
 
 const jsDocPrefix = 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/';
 
-const jsPrimitiveUrl = `${jsDocPrefix}Data_structures`;
+const jsDataStructuresUrl = `${jsDocPrefix}Data_structures`;
 const jsPrimitives = {
-  'boolean': 'Boolean',
+  boolean: 'Boolean',
-  'integer': 'Number', // Not a primitive, used for clarification.
+  integer: 'Number', // Not a primitive, used for clarification.
-  'null': 'Null',
+  null: 'Null',
-  'number': 'Number',
+  number: 'Number',
-  'string': 'String',
+  string: 'String',
-  'symbol': 'Symbol',
+  symbol: 'Symbol',
-  'undefined': 'Undefined'
+  undefined: 'Undefined'
 };
 
 const jsGlobalObjectsUrl = `${jsDocPrefix}Reference/Global_Objects/`;
@@ -25,13 +25,15 @@ const jsGlobalTypes = [
 ];
 
 const customTypesMap = {
+  'any': `${jsDataStructuresUrl}#Data_types`,
+
+  'this': `${jsDocPrefix}Reference/Operators/this`,
+
   'Iterable':
     `${jsDocPrefix}Reference/Iteration_protocols#The_iterable_protocol`,
   'Iterator':
     `${jsDocPrefix}Reference/Iteration_protocols#The_iterator_protocol`,
 
-  'this': `${jsDocPrefix}Reference/Operators/this`,
-
   'AsyncHook': 'async_hooks.html#async_hooks_async_hooks_createhook_callbacks',
 
   'Buffer': 'buffer.html#buffer_class_buffer',
@@ -63,12 +65,14 @@ const customTypesMap = {
   'http.Server': 'http.html#http_class_http_server',
   'http.ServerResponse': 'http.html#http_class_http_serverresponse',
 
+  'ClientHttp2Session': 'http2.html#http2_class_clienthttp2session',
   'ClientHttp2Stream': 'http2.html#http2_class_clienthttp2stream',
   'HTTP/2 Headers Object': 'http2.html#http2_headers_object',
   'HTTP/2 Settings Object': 'http2.html#http2_settings_object',
   'http2.Http2ServerRequest': 'http2.html#http2_class_http2_http2serverrequest',
   'http2.Http2ServerResponse':
     'http2.html#http2_class_http2_http2serverresponse',
+  'Http2SecureServer': 'http2.html#http2_class_http2secureserver',
   'Http2Server': 'http2.html#http2_class_http2server',
   'Http2Session': 'http2.html#http2_class_http2session',
   'Http2Stream': 'http2.html#http2_class_http2stream',
@@ -83,6 +87,8 @@ const customTypesMap = {
   'os.constants.dlopen': 'os.html#os_dlopen_constants',
 
   'PerformanceEntry': 'perf_hooks.html#perf_hooks_class_performanceentry',
+  'PerformanceNodeTiming':
+    'perf_hooks.html#perf_hooks_class_performancenodetiming_extends_performanceentry', // eslint-disable-line max-len
   'PerformanceObserver':
     'perf_hooks.html#perf_hooks_class_performanceobserver_callback',
   'PerformanceObserverEntryList':
@@ -123,10 +129,10 @@ function toLink(typeInput) {
       const typeTextFull = typeText;
       typeText = typeText.replace(arrayPart, '');
 
-      const primitive = jsPrimitives[typeText.toLowerCase()];
+      const primitive = jsPrimitives[typeText];
 
       if (primitive !== undefined) {
-        typeUrl = `${jsPrimitiveUrl}#${primitive}_type`;
+        typeUrl = `${jsDataStructuresUrl}#${primitive}_type`;
       } else if (jsGlobalTypes.includes(typeText)) {
         typeUrl = `${jsGlobalObjectsUrl}${typeText}`;
       } else if (customTypesMap[typeText]) {
@@ -137,7 +143,10 @@ function toLink(typeInput) {
         typeLinks.push(
           `<a href="${typeUrl}" class="type">&lt;${typeTextFull}&gt;</a>`);
       } else {
-        typeLinks.push(`<span class="type">&lt;${typeTextFull}&gt;</span>`);
+        throw new Error(
+          `Unrecognized type: '${typeTextFull}'.\n` +
+          "Please, edit the type or update the 'tools/doc/type-parser.js'."
+        );
       }
     } else {
       throw new Error(`Empty type slot: ${typeInput}`);