doc: make modules.md more accurate

PR-URL: #25357
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

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/

doc/api/errors.md

@@ -2188,7 +2188,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

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

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
 
 <!-- type=var -->
 
+* {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
 
 <!-- type=var -->
 
-* {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)
 <!-- YAML
 added: v0.1.13
 -->
 
 <!-- type=var -->
 
-* {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)
 <!-- YAML
 added: v8.9.0
 -->
@@ -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
 <!-- YAML
@@ -866,9 +869,9 @@ added: v0.5.1
 -->
 
 * `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

tools/doc/type-parser.js

@@ -92,6 +92,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',