From 1091dfc8014c84c24e2bece68e1b33c639285e7a Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Tue, 30 Jan 2018 00:15:53 +0200 Subject: [PATCH] doc: linkify missing types Also, alphabetize all types in type-parser.js and fix some nits in type formats. Backport-PR-URL: https://github.com/nodejs/node/pull/19498 PR-URL: https://github.com/nodejs/node/pull/18444 Reviewed-By: Luigi Pinca Reviewed-By: James M Snell --- doc/api/async_hooks.md | 2 +- doc/api/cluster.md | 2 +- doc/api/console.md | 4 +-- doc/api/fs.md | 2 +- doc/api/http2.md | 4 +-- doc/api/readline.md | 14 +++++------ doc/api/repl.md | 4 +-- doc/api/stream.md | 10 ++++---- tools/doc/type-parser.js | 54 ++++++++++++++++++++++++++++++++-------- 9 files changed, 65 insertions(+), 31 deletions(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 4fa23f28d116b0..781509900cc4c9 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -86,7 +86,7 @@ added: v8.1.0 * `before` {Function} The [`before` callback][]. * `after` {Function} The [`after` callback][]. * `destroy` {Function} The [`destroy` callback][]. -* Returns: `{AsyncHook}` Instance used for disabling and enabling hooks +* Returns: {AsyncHook} Instance used for disabling and enabling hooks Registers functions to be called for different lifetime events of each async operation. diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 00db4a9b5c8915..3b56b4888a696e 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -267,7 +267,7 @@ changes: description: This method now returns a reference to `worker`. --> -* Returns: {Worker} A reference to `worker`. +* Returns: {cluster.Worker} A reference to `worker`. In a worker, this function will close all servers, wait for the `'close'` event on those servers, and then disconnect the IPC channel. diff --git a/doc/api/console.md b/doc/api/console.md index 1f7dea5b2b7f15..7dd4571a781a3b 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -78,8 +78,8 @@ const { Console } = console; ``` ### new Console(stdout[, stderr]) -* `stdout` {Writable} -* `stderr` {Writable} +* `stdout` {stream.Writable} +* `stderr` {stream.Writable} Creates a new `Console` with one or two writable stream instances. `stdout` is a writable stream to print log or info output. `stderr` is used for warning or diff --git a/doc/api/fs.md b/doc/api/fs.md index 1eaae690190c70..d4ee09bd0b9afe 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -577,7 +577,7 @@ changes: * `path` {string|Buffer|URL} * `mode` {integer} **Default:** `fs.constants.F_OK` -* Returns: `undefined` +* Returns: {undefined} Synchronously tests a user's permissions for the file or directory specified by `path`. The `mode` argument is an optional integer that specifies the diff --git a/doc/api/http2.md b/doc/api/http2.md index 31afa378f274ea..df729fac50c14b 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -589,7 +589,7 @@ client. added: v8.4.0 --> -* Extends: {Duplex} +* Extends: {stream.Duplex} Each instance of the `Http2Stream` class represents a bidirectional HTTP/2 communications stream over an `Http2Session` instance. Any single `Http2Session` @@ -1308,7 +1308,7 @@ an `Http2Session` object. If no listener is registered for this event, an added: v8.5.0 --> -* `socket` {http2.ServerHttp2Stream} +* `socket` {ServerHttp2Stream} If an `ServerHttp2Stream` emits an `'error'` event, it will be forwarded here. The stream will already be destroyed when this event is triggered. diff --git a/doc/api/readline.md b/doc/api/readline.md index 7ba1277dce2d9c..42d07da2d0e418 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -323,7 +323,7 @@ Interface's `input` *as if it were provided by the user*. added: v0.7.7 --> -* `stream` {Writable} +* `stream` {stream.Writable} * `dir` {number} * `-1` - to the left from cursor * `1` - to the right from cursor @@ -338,7 +338,7 @@ in a specified direction identified by `dir`. added: v0.7.7 --> -* `stream` {Writable} +* `stream` {stream.Writable} The `readline.clearScreenDown()` method clears the given [TTY][] stream from the current position of the cursor down. @@ -362,9 +362,9 @@ changes: --> * `options` {Object} - * `input` {Readable} The [Readable][] stream to listen to. This option is + * `input` {stream.Readable} The [Readable][] stream to listen to. This option is *required*. - * `output` {Writable} The [Writable][] stream to write readline data to. + * `output` {stream.Writable} The [Writable][] stream to write readline data to. * `completer` {Function} An optional function used for Tab autocompletion. * `terminal` {boolean} `true` if the `input` and `output` streams should be treated like a TTY, and have ANSI/VT100 escape codes written to it. @@ -444,7 +444,7 @@ function completer(linePartial, callback) { added: v0.7.7 --> -* `stream` {Writable} +* `stream` {stream.Writable} * `x` {number} * `y` {number} @@ -456,7 +456,7 @@ given [TTY][] `stream`. added: v0.7.7 --> -* `stream` {Readable} +* `stream` {stream.Readable} * `interface` {readline.Interface} The `readline.emitKeypressEvents()` method causes the given [Readable][] @@ -482,7 +482,7 @@ if (process.stdin.isTTY) added: v0.7.7 --> -* `stream` {Writable} +* `stream` {stream.Writable} * `dx` {number} * `dy` {number} diff --git a/doc/api/repl.md b/doc/api/repl.md index 0ff4ee099cb428..7a54928e187ae2 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -388,9 +388,9 @@ changes: * `options` {Object|string} * `prompt` {string} The input prompt to display. Defaults to `> ` (with a trailing space). - * `input` {Readable} The Readable stream from which REPL input will be read. + * `input` {stream.Readable} The Readable stream from which REPL input will be read. Defaults to `process.stdin`. - * `output` {Writable} The Writable stream to which REPL output will be + * `output` {stream.Writable} The Writable stream to which REPL output will be written. Defaults to `process.stdout`. * `terminal` {boolean} If `true`, specifies that the `output` should be treated as a TTY terminal, and have ANSI/VT100 escape codes written to it. diff --git a/doc/api/stream.md b/doc/api/stream.md index 678ac359caa034..74173abe34f18c 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -394,7 +394,7 @@ changes: --> * `encoding` {string} The new default encoding -* Returns: `this` +* Returns: {this} The `writable.setDefaultEncoding()` method sets the default `encoding` for a [Writable][] stream. @@ -525,7 +525,7 @@ A Writable stream in object mode will always ignore the `encoding` argument. added: v8.0.0 --> -* Returns: `this` +* Returns: {this} Destroy the stream, and emit the passed error. After this call, the writable stream has ended. Implementors should not override this method, @@ -810,7 +810,7 @@ readable.isPaused(); // === false added: v0.9.4 --> -* Returns: `this` +* Returns: {this} The `readable.pause()` method will cause a stream in flowing mode to stop emitting [`'data'`][] events, switching out of flowing mode. Any data that @@ -950,7 +950,7 @@ event has been emitted will return `null`. No runtime error will be raised. added: v0.9.4 --> -* Returns: `this` +* Returns: {this} The `readable.resume()` method causes an explicitly paused Readable stream to resume emitting [`'data'`][] events, switching the stream into flowing mode. @@ -973,7 +973,7 @@ added: v0.9.4 --> * `encoding` {string} The encoding to use. -* Returns: `this` +* Returns: {this} The `readable.setEncoding()` method sets the character encoding for data read from the Readable stream. diff --git a/tools/doc/type-parser.js b/tools/doc/type-parser.js index 3bcdd817a2f134..0ab73162dd59e0 100644 --- a/tools/doc/type-parser.js +++ b/tools/doc/type-parser.js @@ -13,13 +13,13 @@ const jsPrimitives = { 'undefined': 'Undefined' }; const jsGlobalTypes = [ - 'Error', 'Object', 'Function', 'Array', 'TypedArray', 'Uint8Array', - 'Uint16Array', 'Uint32Array', 'Int8Array', 'Int16Array', 'Int32Array', - 'Uint8ClampedArray', 'Float32Array', 'Float64Array', 'Date', 'RegExp', - 'ArrayBuffer', 'DataView', 'Promise', 'EvalError', 'RangeError', - 'ReferenceError', 'SyntaxError', 'TypeError', 'URIError', 'Proxy', 'Map', - 'Set', 'WeakMap', 'WeakSet', 'Generator', 'GeneratorFunction', - 'AsyncFunction', 'SharedArrayBuffer' + 'Array', 'ArrayBuffer', 'AsyncFunction', 'DataView', 'Date', 'Error', + 'EvalError', 'Float32Array', 'Float64Array', 'Function', 'Generator', + 'GeneratorFunction', 'Int16Array', 'Int32Array', 'Int8Array', 'Map', 'Object', + 'Promise', 'Proxy', 'RangeError', 'ReferenceError', 'RegExp', 'Set', + 'SharedArrayBuffer', 'SyntaxError', 'TypeError', 'TypedArray', 'URIError', + 'Uint16Array', 'Uint32Array', 'Uint8Array', 'Uint8ClampedArray', 'WeakMap', + 'WeakSet' ]; const typeMap = { 'Iterable': @@ -27,34 +27,68 @@ const typeMap = { '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', 'ChildProcess': 'child_process.html#child_process_class_childprocess', 'cluster.Worker': 'cluster.html#cluster_class_worker', + 'crypto.constants': 'crypto.html#crypto_crypto_constants_1', + 'dgram.Socket': 'dgram.html#dgram_class_dgram_socket', + 'Domain': 'domain.html#domain_class_domain', + 'EventEmitter': 'events.html#events_class_eventemitter', + 'fs.Stats': 'fs.html#fs_class_fs_stats', + 'http.Agent': 'http.html#http_class_http_agent', 'http.ClientRequest': 'http.html#http_class_http_clientrequest', 'http.IncomingMessage': 'http.html#http_class_http_incomingmessage', 'http.Server': 'http.html#http_class_http_server', 'http.ServerResponse': 'http.html#http_class_http_serverresponse', + 'ClientHttp2Stream': 'http2.html#http2_class_clienthttp2stream', + 'HTTP2 Headers Object': 'http2.html#http2_headers_object', + 'HTTP2 Settings Object': 'http2.html#http2_settings_object', + 'http2.Http2ServerRequest': 'http2.html#http2_class_http2_http2serverrequest', + 'http2.Http2ServerResponse': + 'http2.html#http2_class_http2_http2serverresponse', + 'Http2Server': 'http2.html#http2_class_http2server', + 'Http2Session': 'http2.html#http2_class_http2session', + 'Http2Stream': 'http2.html#http2_class_http2stream', + 'ServerHttp2Stream': 'http2.html#http2_class_serverhttp2stream', + 'Handle': 'net.html#net_server_listen_handle_backlog_callback', + 'net.Server': 'net.html#net_class_net_server', 'net.Socket': 'net.html#net_class_net_socket', + 'os.constants.dlopen': 'os.html#os_dlopen_constants', + + 'PerformanceObserver': + 'perf_hooks.html#perf_hooks_class_performanceobserver_callback', + 'PerformanceObserverEntryList': + 'perf_hooks.html#perf_hooks_class_performanceobserverentrylist', + + 'readline.Interface': 'readline.html#readline_class_interface', + 'Stream': 'stream.html#stream_stream', + 'stream.Duplex': 'stream.html#stream_class_stream_duplex', 'stream.Readable': 'stream.html#stream_class_stream_readable', 'stream.Writable': 'stream.html#stream_class_stream_writable', - 'stream.Duplex': 'stream.html#stream_class_stream_duplex', - - 'tls.TLSSocket': 'tls.html#tls_class_tls_tlssocket', + 'Immediate': 'timers.html#timers_class_immediate', + 'Timeout': 'timers.html#timers_class_timeout', 'Timer': 'timers.html#timers_timers', + 'tls.Server': 'tls.html#tls_class_tls_server', + 'tls.TLSSocket': 'tls.html#tls_class_tls_tlssocket', + 'URL': 'url.html#url_the_whatwg_url_api', 'URLSearchParams': 'url.html#url_class_urlsearchparams' };