doc: move module-specific "globals" to modules.md

PR-URL: https://github.com/nodejs/node/pull/13962
Fixes: https://github.com/nodejs/node/issues/13953
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>

3 files changed, 177 insertions, 155 deletions

diff --git a/doc/api/addons.md b/doc/api/addons.md
index 8c08c5492e..e973ec4111 100644
--- a/doc/api/addons.md
+++ b/doc/api/addons.md
@@ -1137,5 +1137,5 @@ const addon = 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]: globals.html#globals_require
+[require]: modules.html#modules_require
 [v8-docs]: https://v8docs.nodesource.com/
diff --git a/doc/api/globals.md b/doc/api/globals.md
index c91acb3244..f3a2fc6377 100644
--- a/doc/api/globals.md
+++ b/doc/api/globals.md
@@ -2,8 +2,15 @@
 
 <!-- type=misc -->
 
-These objects are available in all modules. Some of these objects aren't
-actually in the global scope but in the module scope - this will be noted.
+These objects are available in all modules. The following variables may appear
+to be global but are not. They exist only in the scope of modules, see the
+[module system documentation][]:
+
+- [`__dirname`][]
+- [`__filename`][]
+- [`exports`][]
+- [`module`][]
+- [`require()`][]
 
 The objects listed here are specific to Node.js. There are a number of
 [built-in objects][] that are part of the JavaScript language itself, which are
@@ -21,67 +28,12 @@ added: v0.1.103
 Used to handle binary data. See the [buffer section][].
 
 ## \_\_dirname
-<!-- YAML
-added: v0.1.27
--->
-
-<!-- type=var -->
-
-* {string}
-
-The directory name of the current module. This the same as the
-[`path.dirname()`][] of the [`__filename`][].
-
-`__dirname` is not actually a global but rather local to each module.
 
-Example: running `node example.js` from `/Users/mjr`
-
-```js
-console.log(__dirname);
-// Prints: /Users/mjr
-console.log(path.dirname(__filename));
-// Prints: /Users/mjr
-```
+This variable may appear to be global but is not. See [`__dirname`].
 
 ## \_\_filename
-<!-- YAML
-added: v0.0.1
--->
-
-<!-- type=var -->
-
-* {string}
-
-The file name of the current module. This is the resolved absolute path of the
-current module file.
-
-For a main program this is not necessarily the same as the file name used in the
-command line.
 
-See [`__dirname`][] for the directory name of the current module.
-
-`__filename` is not actually a global but rather local to each module.
-
-Examples:
-
-Running `node example.js` from `/Users/mjr`
-
-```js
-console.log(__filename);
-// Prints: /Users/mjr/example.js
-console.log(__dirname);
-// Prints: /Users/mjr
-```
-
-Given two modules: `a` and `b`, where `b` is a dependency of
-`a` and there is a directory structure of:
-
-* `/Users/mjr/app/a.js`
-* `/Users/mjr/app/node_modules/b/b.js`
-
-References to `__filename` within `b.js` will return
-`/Users/mjr/app/node_modules/b/b.js` while references to `__filename` within
-`a.js` will return `/Users/mjr/app/a.js`.
+This variable may appear to be global but is not. See [`__filename`].
 
 ## clearImmediate(immediateObject)
 <!-- YAML
@@ -122,19 +74,8 @@ added: v0.1.100
 Used to print to stdout and stderr. See the [`console`][] section.
 
 ## exports
-<!-- YAML
-added: v0.1.12
--->
-
-<!-- type=var -->
-
-A reference to the `module.exports` that is shorter to type.
-See [module system documentation][] for details on when to use `exports` and
-when to use `module.exports`.
-
-`exports` is not actually a global but rather local to each module.
 
-See the [module system documentation][] for more information.
+This variable may appear to be global but is not. See [`exports`].
 
 ## global
 <!-- YAML
@@ -151,21 +92,8 @@ Node.js this is different. The top-level scope is not the global scope;
 `var something` inside a Node.js module will be local to that module.
 
 ## module
-<!-- YAML
-added: v0.1.16
--->
 
-<!-- type=var -->
-
-* {Object}
-
-A reference to the current module. In particular
-`module.exports` is used for defining what a module exports and makes
-available through `require()`.
-
-`module` is not actually a global but rather local to each module.
-
-See the [module system documentation][] for more information.
+This variable may appear to be global but is not. See [`module`].
 
 ## process
 <!-- YAML
@@ -179,71 +107,8 @@ added: v0.1.7
 The process object. See the [`process` object][] section.
 
 ## require()
-<!-- YAML
-added: v0.1.13
--->
-
-<!-- type=var -->
-
-* {Function}
-
-To require modules. See the [Modules][] section.  `require` is not actually a
-global but rather local to each module.
-
-### require.cache
-<!-- YAML
-added: v0.3.0
--->
-
-* {Object}
-
-Modules are cached in this object when they are required. By deleting a key
-value from this object, the next `require` will reload the module. Note that
-this does not apply to [native addons][], for which reloading will result in an
-Error.
-
-### require.extensions
-<!-- YAML
-added: v0.3.0
-deprecated: v0.10.6
--->
-
-> Stability: 0 - Deprecated
-
-* {Object}
-
-Instruct `require` on how to handle certain file extensions.
-
-Process files with the extension `.sjs` as `.js`:
-
-```js
-require.extensions['.sjs'] = require.extensions['.js'];
-```
-
-**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
-JavaScript ahead of time.
-
-Since the module system is locked, this feature will probably never go
-away.  However, it may have subtle bugs and complexities that are best
-left untouched.
-
-Note that the number of file system operations that the module system
-has to perform in order to resolve a `require(...)` statement to a
-filename scales linearly with the number of registered extensions.
-
-In other words, adding extensions slows down the module loader and
-should be discouraged.
-
-### require.resolve()
-<!-- YAML
-added: v0.3.0
--->
 
-Use the internal `require()` machinery to look up the location of a module,
-but rather than loading the module, just return the resolved filename.
+This variable may appear to be global but is not. See [`require()`].
 
 ## setImmediate(callback[, ...args])
 <!-- YAML
@@ -272,20 +137,20 @@ added: v0.0.1
 
 [`setTimeout`] is described in the [timers][] section.
 
-[`__dirname`]: #globals_dirname
-[`__filename`]: #globals_filename
+[`__dirname`]: modules.html#modules_dirname
+[`__filename`]: modules.html#modules_filename
 [`clearImmediate`]: timers.html#timers_clearimmediate_immediate
 [`clearInterval`]: timers.html#timers_clearinterval_timeout
 [`clearTimeout`]: timers.html#timers_cleartimeout_timeout
 [`console`]: console.html
-[`path.dirname()`]: path.html#path_path_dirname_path
+[`exports`]: modules.html#modules_exports
+[`module`]: modules.html#modules_module
 [`process` object]: process.html#process_process
+[`require()`]: modules.html#modules_require
 [`setImmediate`]: timers.html#timers_setimmediate_callback_args
 [`setInterval`]: timers.html#timers_setinterval_callback_delay_args
 [`setTimeout`]: timers.html#timers_settimeout_callback_delay_args
-[Modules]: modules.html#modules_modules
 [buffer section]: buffer.html
 [built-in objects]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects
 [module system documentation]: modules.html
-[native addons]: addons.html
 [timers]: timers.html
diff --git a/doc/api/modules.md b/doc/api/modules.md
index adbefb8120..e07e21217c 100644
--- a/doc/api/modules.md
+++ b/doc/api/modules.md
@@ -453,6 +453,157 @@ to the module, such as:
   - The convenience variables `__filename` and `__dirname`, containing the
   module's absolute filename and directory path.
 
+## The module scope
+
+### \_\_dirname
+<!-- YAML
+added: v0.1.27
+-->
+
+<!-- type=var -->
+
+* {string}
+
+The directory name of the current module. This the same as the
+[`path.dirname()`][] of the [`__filename`][].
+
+Example: running `node example.js` from `/Users/mjr`
+
+```js
+console.log(__dirname);
+// Prints: /Users/mjr
+console.log(path.dirname(__filename));
+// Prints: /Users/mjr
+```
+
+### \_\_filename
+<!-- YAML
+added: v0.0.1
+-->
+
+<!-- type=var -->
+
+* {string}
+
+The file name of the current module. This is the resolved absolute path of the
+current module file.
+
+For a main program this is not necessarily the same as the file name used in the
+command line.
+
+See [`__dirname`][] for the directory name of the current module.
+
+Examples:
+
+Running `node example.js` from `/Users/mjr`
+
+```js
+console.log(__filename);
+// Prints: /Users/mjr/example.js
+console.log(__dirname);
+// Prints: /Users/mjr
+```
+
+Given two modules: `a` and `b`, where `b` is a dependency of
+`a` and there is a directory structure of:
+
+* `/Users/mjr/app/a.js`
+* `/Users/mjr/app/node_modules/b/b.js`
+
+References to `__filename` within `b.js` will return
+`/Users/mjr/app/node_modules/b/b.js` while references to `__filename` within
+`a.js` will return `/Users/mjr/app/a.js`.
+
+### exports
+<!-- YAML
+added: v0.1.12
+-->
+
+<!-- type=var -->
+
+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`.
+
+### module
+<!-- YAML
+added: v0.1.16
+-->
+
+<!-- type=var -->
+
+* {Object}
+
+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()
+<!-- YAML
+added: v0.1.13
+-->
+
+<!-- type=var -->
+
+* {Function}
+
+To require modules.
+
+#### require.cache
+<!-- YAML
+added: v0.3.0
+-->
+
+* {Object}
+
+Modules are cached in this object when they are required. By deleting a key
+value from this object, the next `require` will reload the module. Note that
+this does not apply to [native addons][], for which reloading will result in an
+Error.
+
+#### require.extensions
+<!-- YAML
+added: v0.3.0
+deprecated: v0.10.6
+-->
+
+> Stability: 0 - Deprecated
+
+* {Object}
+
+Instruct `require` on how to handle certain file extensions.
+
+Process files with the extension `.sjs` as `.js`:
+
+```js
+require.extensions['.sjs'] = require.extensions['.js'];
+```
+
+**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
+JavaScript ahead of time.
+
+Since the module system is locked, this feature will probably never go
+away.  However, it may have subtle bugs and complexities that are best
+left untouched.
+
+Note that the number of file system operations that the module system
+has to perform in order to resolve a `require(...)` statement to a
+filename scales linearly with the number of registered extensions.
+
+In other words, adding extensions slows down the module loader and
+should be discouraged.
+
+#### require.resolve()
+<!-- YAML
+added: v0.3.0
+-->
+
+Use the internal `require()` machinery to look up the location of a module,
+but rather than loading the module, just return the resolved filename.
+
 ## The `module` Object
 <!-- YAML
 added: v0.1.16
@@ -633,5 +784,11 @@ The `module.require` method provides a way to load a module as if
 `module` is typically *only* available within a specific module's code, it must
 be explicitly exported in order to be used.
 
+[`__dirname`]: #modules_dirname
+[`__filename`]: #modules_filename
 [`Error`]: errors.html#errors_class_error
+[`module` object]: #modules_the_module_object
+[`path.dirname()`]: path.html#path_path_dirname_path
+[exports shortcut]: #modules_exports_shortcut
 [module resolution]: #modules_all_together
+[native addons]: addons.html
\ No newline at end of file