From 49ec37197c9dd86c178a5c593ab39a404f377a53 Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Sun, 6 Jan 2019 00:44:49 +0200 Subject: [PATCH] doc: make modules.md more accurate PR-URL: https://github.com/nodejs/node/pull/25357 Reviewed-By: Anna Henningsen Reviewed-By: Colin Ihrig --- doc/api/addons.md | 2 +- doc/api/errors.md | 2 +- doc/api/globals.md | 2 +- doc/api/modules.md | 28 +++++++++++++++------------- tools/doc/type-parser.js | 1 + 5 files changed, 19 insertions(+), 16 deletions(-) diff --git a/doc/api/addons.md b/doc/api/addons.md index 9bc75c7dfc15d1..4941d3de9add8f 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -1377,5 +1377,5 @@ require('./build/Release/addon'); [installation instructions]: https://github.com/nodejs/node-gyp#installation [libuv]: https://github.com/libuv/libuv [node-gyp]: https://github.com/nodejs/node-gyp -[require]: modules.html#modules_require +[require]: modules.html#modules_require_id [v8-docs]: https://v8docs.nodesource.com/ diff --git a/doc/api/errors.md b/doc/api/errors.md index d7e0023e3e7830..15bd04673d18b2 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -2178,7 +2178,7 @@ such as `process.stdout.on('data')`. [`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn [`readable._read()`]: stream.html#stream_readable_read_size_1 [`require('crypto').setEngine()`]: crypto.html#crypto_crypto_setengine_engine_flags -[`require()`]: modules.html#modules_require +[`require()`]: modules.html#modules_require_id [`server.close()`]: net.html#net_server_close_callback [`server.listen()`]: net.html#net_server_listen [`sign.sign()`]: crypto.html#crypto_sign_sign_privatekey_outputencoding diff --git a/doc/api/globals.md b/doc/api/globals.md index 418e95ea459bc6..779aa2653884da 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -242,7 +242,7 @@ The object that acts as the namespace for all W3C [`exports`]: modules.html#modules_exports [`module`]: modules.html#modules_module [`process` object]: process.html#process_process -[`require()`]: modules.html#modules_require +[`require()`]: modules.html#modules_require_id [`setImmediate`]: timers.html#timers_setimmediate_callback_args [`setInterval`]: timers.html#timers_setinterval_callback_delay_args [`setTimeout`]: timers.html#timers_settimeout_callback_delay_args diff --git a/doc/api/modules.md b/doc/api/modules.md index 5292d2389760bd..222cf71f35c5ca 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -313,7 +313,7 @@ required filename with the added extensions: `.js`, `.json`, and finally `.js` files are interpreted as JavaScript text files, and `.json` files are parsed as JSON text files. `.node` files are interpreted as compiled addon -modules loaded with `dlopen`. +modules loaded with `process.dlopen()`. A required module prefixed with `'/'` is an absolute path to the file. For example, `require('/home/marco/foo.js')` will load the file at @@ -527,6 +527,8 @@ added: v0.1.12 +* {Object} + A reference to the `module.exports` that is shorter to type. See the section about the [exports shortcut][] for details on when to use `exports` and when to use `module.exports`. @@ -538,20 +540,21 @@ added: v0.1.16 -* {Object} +* {module} A reference to the current module, see the section about the [`module` object][]. In particular, `module.exports` is used for defining what a module exports and makes available through `require()`. -### require() +### require(id) -* {Function} +* `id` {string} module name or path +* Returns: {any} exported module content Used to import modules, `JSON`, and local files. Modules can be imported from `node_modules`. Local modules and JSON files can be imported using @@ -600,7 +603,7 @@ Process files with the extension `.sjs` as `.js`: require.extensions['.sjs'] = require.extensions['.js']; ``` -**Deprecated** In the past, this list has been used to load +**Deprecated.** In the past, this list has been used to load non-JavaScript modules into Node.js by compiling them on-demand. However, in practice, there are much better ways to do this, such as loading modules via some other Node.js program, or compiling them to @@ -622,7 +625,7 @@ should be discouraged. added: v0.1.17 --> -* {Object} +* {module} The `Module` object representing the entry script loaded when the Node.js process launched. @@ -676,7 +679,7 @@ changes: Use the internal `require()` machinery to look up the location of a module, but rather than loading the module, just return the resolved filename. -#### require.resolve.paths(request) +##### require.resolve.paths(request) @@ -820,7 +823,7 @@ added: v0.1.16 * {string} -The fully resolved filename to the module. +The fully resolved filename of the module. ### module.id * `id` {string} -* Returns: {Object} `module.exports` from the resolved module +* Returns: {any} exported module content -The `module.require` method provides a way to load a module as if +The `module.require()` method provides a way to load a module as if `require()` was called from the original module. In order to do this, it is necessary to get a reference to the `module` object. @@ -912,7 +915,7 @@ added: v10.12.0 * `filename` {string} Filename to be used to construct the relative require function. -* Returns: {[`require`][]} Require function +* Returns: {require} Require function ```js const { createRequireFromPath } = require('module'); @@ -922,13 +925,12 @@ const requireUtil = createRequireFromPath('../src/utils'); requireUtil('./some-tool'); ``` +[GLOBAL_FOLDERS]: #modules_loading_from_the_global_folders [`Error`]: errors.html#errors_class_error [`__dirname`]: #modules_dirname [`__filename`]: #modules_filename [`module` object]: #modules_the_module_object [`path.dirname()`]: path.html#path_path_dirname_path -[`require`]: #modules_require -[GLOBAL_FOLDERS]: #modules_loading_from_the_global_folders [exports shortcut]: #modules_exports_shortcut [module resolution]: #modules_all_together [module wrapper]: #modules_the_module_wrapper diff --git a/tools/doc/type-parser.js b/tools/doc/type-parser.js index e3588856209e28..9de3777b2b8f02 100644 --- a/tools/doc/type-parser.js +++ b/tools/doc/type-parser.js @@ -90,6 +90,7 @@ const customTypesMap = { 'https.Server': 'https.html#https_class_https_server', 'module': 'modules.html#modules_the_module_object', + 'require': 'modules.html#modules_require_id', 'Handle': 'net.html#net_server_listen_handle_backlog_callback', 'net.Server': 'net.html#net_class_net_server',