Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc, tools: make type parsing more strict #19881

Closed
wants to merge 2 commits into from
Closed

doc, tools: make type parsing more strict #19881

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bf418d6
doc, tools: make type parsing more strict
vsemozhetbyt Apr 8, 2018
104e977
fixup: address review
vsemozhetbyt Apr 8, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions doc/api/addons.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` <span class="type">&lt;void (\*)(void\*)&gt;</span>
A pointer to the function to call at exit.
* `args` <span class="type">&lt;void\*&gt;</span>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

were these changed so they don't trigger the type parser?

Copy link
Contributor Author

@vsemozhetbyt vsemozhetbyt Apr 8, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. Currently, tools/doc/html.js type-process any non-code text in any section, so it cannot define if this is a js type or something else. But the author of this section wanted the C types to be consistent in CSS style with JS types, so I've tried to conform.

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.
Expand Down
7 changes: 4 additions & 3 deletions doc/api/deprecations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -886,12 +886,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
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
Expand Down
4 changes: 2 additions & 2 deletions doc/api/http2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2521,7 +2521,7 @@ authentication details.
added: v8.4.0
-->

* {http2.Http2Stream}
* {Http2Stream}

The [`Http2Stream`][] object backing the request.

Expand Down Expand Up @@ -2937,7 +2937,7 @@ an empty string.
added: v8.4.0
-->

* {http2.Http2Stream}
* {Http2Stream}

The [`Http2Stream`][] object backing the response.

Expand Down
6 changes: 3 additions & 3 deletions doc/api/process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -1531,7 +1531,7 @@ added: v0.5.9
-->

* `message` {Object}
* `sendHandle` {Handle object}
* `sendHandle` {net.Server|net.Socket}
* `options` {Object}
* `callback` {Function}
* Returns: {boolean}
Expand Down
35 changes: 22 additions & 13 deletions tools/doc/type-parser.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/`;
Expand All @@ -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',
Expand Down Expand Up @@ -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',
Expand All @@ -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':
Expand Down Expand Up @@ -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]) {
Expand All @@ -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}`);
Expand Down