From b3bff41690dbbb937d20b7f2c484b72b1f8e3440 Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Sun, 8 Apr 2018 16:53:47 +0300 Subject: [PATCH] doc, tools: make type parsing more strict PR-URL: https://github.com/nodejs/node/pull/19881 Reviewed-By: Gus Caplan Reviewed-By: Ruben Bridgewater Reviewed-By: Luigi Pinca Reviewed-By: Trivikram Kamat --- doc/api/addons.md | 6 ++++-- doc/api/deprecations.md | 7 ++++--- doc/api/http2.md | 4 ++-- doc/api/process.md | 6 +++--- tools/doc/type-parser.js | 35 ++++++++++++++++++++++------------- 5 files changed, 35 insertions(+), 23 deletions(-) diff --git a/doc/api/addons.md b/doc/api/addons.md index e52e43153e6982..16040e85352c77 100644 --- a/doc/api/addons.md +++ b/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. -* `args` {void\*} A pointer to pass to the callback at exit. +* `callback` <void (\*)(void\*)> + A pointer to the function to call at exit. +* `args` <void\*> + 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. diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index b78244b5d5b015..0a22723c65e0a5 100644 --- a/doc/api/deprecations.md +++ b/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. -### 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 -which are very easy to use incorrectly which can lead to unrecoverable errors. +The embedded API provided by AsyncHooks exposes `.emitBefore()` and +`.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 diff --git a/doc/api/http2.md b/doc/api/http2.md index 1c4980cb8b8952..4bb62e9124ac49 100644 --- a/doc/api/http2.md +++ b/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. diff --git a/doc/api/process.md b/doc/api/process.md index e80e187cc16805..c454d67574655b 100644 --- a/doc/api/process.md +++ b/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 - undefined. +* `sendHandle` {net.Server|net.Socket} a [`net.Server`][] or [`net.Socket`][] + 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} diff --git a/tools/doc/type-parser.js b/tools/doc/type-parser.js index 84a87498762930..f1e634a04e4400 100644 --- a/tools/doc/type-parser.js +++ b/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', - 'integer': 'Number', // Not a primitive, used for clarification. - 'null': 'Null', - 'number': 'Number', - 'string': 'String', - 'symbol': 'Symbol', - 'undefined': 'Undefined' + boolean: 'Boolean', + integer: 'Number', // Not a primitive, used for clarification. + null: 'Null', + number: 'Number', + string: 'String', + symbol: 'Symbol', + 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( `<${typeTextFull}>`); } else { - typeLinks.push(`<${typeTextFull}>`); + 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}`);