From 8ec4856941eb1e3bc815dc94ad7594386b26fbb9 Mon Sep 17 00:00:00 2001 From: Ouyang Yadong Date: Wed, 31 Oct 2018 16:53:38 +0800 Subject: [PATCH] doc: add types and their corresponding return values This commit supplements some types and their corresponding return values in docs, including `AsyncResource`, `DiffieHellman`, `ECDH`, `https.Server`, `repl.REPLServer`. PR-URL: https://github.com/nodejs/node/pull/23998 Reviewed-By: Vse Mozhet Byt Reviewed-By: Luigi Pinca --- doc/api/async_hooks.md | 2 ++ doc/api/crypto.md | 5 ++++- doc/api/https.md | 3 +++ doc/api/repl.md | 1 + doc/api/tls.md | 5 +++++ tools/doc/type-parser.js | 7 +++++++ 6 files changed, 22 insertions(+), 1 deletion(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 252ded2ca41b2c..f0752a5892c362 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -704,6 +704,8 @@ alternative. #### asyncResource.emitDestroy() +* Returns: {AsyncResource} A reference to `asyncResource`. + Call all `destroy` hooks. This should only ever be called once. An error will be thrown if it is called more than once. This **must** be manually called. If the resource is left to be collected by the GC then the `destroy` hooks will diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 4dbdc101018a96..30e0a50f3fde27 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1555,6 +1555,7 @@ changes: * `generator` {number | string | Buffer | TypedArray | DataView} **Default:** `2` * `generatorEncoding` {string} +* Returns: {DiffieHellman} Creates a `DiffieHellman` key exchange object using the supplied `prime` and an optional specific `generator`. @@ -1578,6 +1579,7 @@ added: v0.5.0 * `primeLength` {number} * `generator` {number | string | Buffer | TypedArray | DataView} **Default:** `2` +* Returns: {DiffieHellman} Creates a `DiffieHellman` key exchange object and generates a prime of `primeLength` bits using an optional specific numeric `generator`. @@ -1588,6 +1590,7 @@ If `generator` is not specified, the value `2` is used. added: v0.11.14 --> * `curveName` {string} +* Returns: {ECDH} Creates an Elliptic Curve Diffie-Hellman (`ECDH`) key exchange object using a predefined curve specified by the `curveName` string. Use @@ -1840,7 +1843,7 @@ console.log(curves); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...] added: v0.7.5 --> * `groupName` {string} -* Returns: {Object} +* Returns: {DiffieHellman} Creates a predefined `DiffieHellman` key exchange object. The supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in diff --git a/doc/api/https.md b/doc/api/https.md index 21317f83a4486a..b61a4bef08d22d 100644 --- a/doc/api/https.md +++ b/doc/api/https.md @@ -28,6 +28,7 @@ This class is a subclass of `tls.Server` and emits events same as added: v0.1.90 --> * `callback` {Function} +* Returns: {https.Server} See [`server.close()`][`http.close()`] from the HTTP module for details. @@ -55,6 +56,7 @@ added: v0.11.2 --> * `msecs` {number} **Default:** `120000` (2 minutes) * `callback` {Function} +* Returns: {https.Server} See [`http.Server#setTimeout()`][]. @@ -81,6 +83,7 @@ added: v0.3.4 * `options` {Object} Accepts `options` from [`tls.createServer()`][], [`tls.createSecureContext()`][] and [`http.createServer()`][]. * `requestListener` {Function} A listener to be added to the `'request'` event. +* Returns: {https.Server} ```js // curl -k https://localhost:8000/ diff --git a/doc/api/repl.md b/doc/api/repl.md index d010265327e5fa..09fe9ebcbece61 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -499,6 +499,7 @@ changes: * `breakEvalOnSigint` - Stop evaluating the current piece of code when `SIGINT` is received, i.e. `Ctrl+C` is pressed. This cannot be used together with a custom `eval` function. **Default:** `false`. +* Returns: {repl.REPLServer} The `repl.start()` method creates and starts a [`repl.REPLServer`][] instance. diff --git a/doc/api/tls.md b/doc/api/tls.md index d6ead9060182c5..30dfb9c31e01fe 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -378,6 +378,7 @@ added: v0.3.2 * `callback` {Function} A listener callback that will be registered to listen for the server instance's `'close'` event. +* Returns: {tls.Server} The `server.close()` method stops the server from accepting new connections. @@ -911,6 +912,7 @@ changes: * ...: [`tls.createSecureContext()`][] options that are used if the `secureContext` option is missing, otherwise they are ignored. * `callback` {Function} +* Returns: {tls.TLSSocket} The `callback` function, if specified, will be added as a listener for the [`'secureConnect'`][] event. @@ -985,6 +987,7 @@ added: v0.11.3 * `path` {string} Default value for `options.path`. * `options` {Object} See [`tls.connect()`][]. * `callback` {Function} See [`tls.connect()`][]. +* Returns: {tls.TLSSocket} Same as [`tls.connect()`][] except that `path` can be provided as an argument instead of an option. @@ -1000,6 +1003,7 @@ added: v0.11.3 * `host` {string} Default value for `options.host`. * `options` {Object} See [`tls.connect()`][]. * `callback` {Function} See [`tls.connect()`][]. +* Returns: {tls.TLSSocket} Same as [`tls.connect()`][] except that `port` and `host` can be provided as arguments instead of options. @@ -1172,6 +1176,7 @@ changes: * ...: Any [`tls.createSecureContext()`][] option can be provided. For servers, the identity options (`pfx` or `key`/`cert`) are usually required. * `secureConnectionListener` {Function} +* Returns: {tls.Server} Creates a new [`tls.Server`][]. The `secureConnectionListener`, if provided, is automatically set as a listener for the [`'secureConnection'`][] event. diff --git a/tools/doc/type-parser.js b/tools/doc/type-parser.js index b57dc6957a9ae0..49d888e88b9900 100644 --- a/tools/doc/type-parser.js +++ b/tools/doc/type-parser.js @@ -36,6 +36,7 @@ const customTypesMap = { `${jsDocPrefix}Reference/Iteration_protocols#The_iterator_protocol`, 'AsyncHook': 'async_hooks.html#async_hooks_async_hooks_createhook_callbacks', + 'AsyncResource': 'async_hooks.html#async_hooks_class_asyncresource', 'Buffer': 'buffer.html#buffer_class_buffer', @@ -45,6 +46,8 @@ const customTypesMap = { 'Cipher': 'crypto.html#crypto_class_cipher', 'Decipher': 'crypto.html#crypto_class_decipher', + 'DiffieHellman': 'crypto.html#crypto_class_diffiehellman', + 'ECDH': 'crypto.html#crypto_class_ecdh', 'Hash': 'crypto.html#crypto_class_hash', 'Hmac': 'crypto.html#crypto_class_hmac', 'Sign': 'crypto.html#crypto_class_sign', @@ -83,6 +86,8 @@ const customTypesMap = { 'Http2Stream': 'http2.html#http2_class_http2stream', 'ServerHttp2Stream': 'http2.html#http2_class_serverhttp2stream', + 'https.Server': 'https.html#https_class_https_server', + 'module': 'modules.html#modules_the_module_object', 'Handle': 'net.html#net_server_listen_handle_backlog_callback', @@ -101,6 +106,8 @@ const customTypesMap = { 'readline.Interface': 'readline.html#readline_class_interface', + 'repl.REPLServer': 'repl.html#repl_class_replserver', + 'Stream': 'stream.html#stream_stream', 'stream.Duplex': 'stream.html#stream_class_stream_duplex', 'stream.Readable': 'stream.html#stream_class_stream_readable',