doc: move module core module doc to separate page

The `module` core module is available for both CJS and ESM users, it
deserves its own page.

PR-URL: https://github.com/nodejs/node/pull/34747
Refs: https://github.com/nodejs/modules/issues/539
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>

5 files changed, 213 insertions, 183 deletions

diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index 9a93719a22..8333597513 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -2644,7 +2644,7 @@ const moduleParents = Object.values(require.cache)
 [`http.request()`]: http.html#http_http_request_options_callback
 [`https.get()`]: https.html#https_https_get_options_callback
 [`https.request()`]: https.html#https_https_request_options_callback
-[`module.createRequire()`]: modules.html#modules_module_createrequire_filename
+[`module.createRequire()`]: module.html#module_module_createrequire_filename
 [`os.networkInterfaces()`]: os.html#os_os_networkinterfaces
 [`os.tmpdir()`]: os.html#os_os_tmpdir
 [`process.env`]: process.html#process_process_env
diff --git a/doc/api/esm.md b/doc/api/esm.md
index 4d2b8dfdec..ac0f10f51a 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -1278,8 +1278,8 @@ success!
 [`import()`]: #esm_import_expressions
 [`import.meta.url`]: #esm_import_meta
 [`import`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import
-[`module.createRequire()`]: modules.html#modules_module_createrequire_filename
-[`module.syncBuiltinESMExports()`]: modules.html#modules_module_syncbuiltinesmexports
+[`module.createRequire()`]: module.html#module_module_createrequire_filename
+[`module.syncBuiltinESMExports()`]: module.html#module_module_syncbuiltinesmexports
 [`transformSource` hook]: #esm_transformsource_source_context_defaulttransformsource
 [`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
 [`SharedArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
diff --git a/doc/api/index.md b/doc/api/index.md
index ce1af23c6b..1363822450 100644
--- a/doc/api/index.md
+++ b/doc/api/index.md
@@ -36,6 +36,7 @@
 * [Internationalization](intl.html)
 * [Modules: CommonJS modules](modules.html)
 * [Modules: ECMAScript modules](esm.html)
+* [Modules: `module` API](module.html)
 * [Modules: Packages](packages.html)
 * [Net](net.html)
 * [OS](os.html)
diff --git a/doc/api/module.md b/doc/api/module.md
new file mode 100644
index 0000000000..9ce16900fb
--- /dev/null
+++ b/doc/api/module.md
@@ -0,0 +1,194 @@
+# Modules: `module` API
+
+<!--introduced_in=v0.3.7-->
+
+## The `Module` object
+
+* {Object}
+
+Provides general utility methods when interacting with instances of
+`Module`, the `module` variable often seen in file modules. Accessed
+via `require('module')`.
+
+### `module.builtinModules`
+<!-- YAML
+added:
+  - v9.3.0
+  - v8.10.0
+  - v6.13.0
+-->
+
+* {string[]}
+
+A list of the names of all modules provided by Node.js. Can be used to verify
+if a module is maintained by a third party or not.
+
+`module` in this context isn't the same object that's provided
+by the [module wrapper][]. To access it, require the `Module` module:
+
+```js
+const builtin = require('module').builtinModules;
+```
+
+### `module.createRequire(filename)`
+<!-- YAML
+added: v12.2.0
+-->
+
+* `filename` {string|URL} Filename to be used to construct the require
+  function. Must be a file URL object, file URL string, or absolute path
+  string.
+* Returns: {require} Require function
+
+```js
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+// sibling-module.js is a CommonJS module.
+const siblingModule = require('./sibling-module');
+```
+
+### `module.createRequireFromPath(filename)`
+<!-- YAML
+added: v10.12.0
+deprecated: v12.2.0
+-->
+
+> Stability: 0 - Deprecated: Please use [`createRequire()`][] instead.
+
+* `filename` {string} Filename to be used to construct the relative require
+  function.
+* Returns: {require} Require function
+
+```js
+const { createRequireFromPath } = require('module');
+const requireUtil = createRequireFromPath('../src/utils/');
+
+// Require `../src/utils/some-tool`
+requireUtil('./some-tool');
+```
+
+### `module.syncBuiltinESMExports()`
+<!-- YAML
+added: v12.12.0
+-->
+
+The `module.syncBuiltinESMExports()` method updates all the live bindings for
+builtin ES Modules to match the properties of the CommonJS exports. It does
+not add or remove exported names from the ES Modules.
+
+```js
+const fs = require('fs');
+const { syncBuiltinESMExports } = require('module');
+
+fs.readFile = null;
+
+delete fs.readFileSync;
+
+fs.newAPI = function newAPI() {
+  // ...
+};
+
+syncBuiltinESMExports();
+
+import('fs').then((esmFS) => {
+  assert.strictEqual(esmFS.readFile, null);
+  assert.strictEqual('readFileSync' in fs, true);
+  assert.strictEqual(esmFS.newAPI, undefined);
+});
+```
+
+## Source map v3 support
+<!-- YAML
+added:
+ - v13.7.0
+ - v12.17.0
+-->
+
+> Stability: 1 - Experimental
+
+Helpers for interacting with the source map cache. This cache is
+populated when source map parsing is enabled and
+[source map include directives][] are found in a modules' footer.
+
+To enable source map parsing, Node.js must be run with the flag
+[`--enable-source-maps`][], or with code coverage enabled by setting
+[`NODE_V8_COVERAGE=dir`][].
+
+```js
+const { findSourceMap, SourceMap } = require('module');
+```
+
+### `module.findSourceMap(path[, error])`
+<!-- YAML
+added:
+ - v13.7.0
+ - v12.17.0
+-->
+
+* `path` {string}
+* `error` {Error}
+* Returns: {module.SourceMap}
+
+`path` is the resolved path for the file for which a corresponding source map
+should be fetched.
+
+The `error` instance should be passed as the second parameter to `findSourceMap`
+in exceptional flows, e.g., when an overridden
+[`Error.prepareStackTrace(error, trace)`][] is invoked. Modules are not added to
+the module cache until they are successfully loaded, in these cases source maps
+will be associated with the `error` instance along with the `path`.
+
+### Class: `module.SourceMap`
+<!-- YAML
+added:
+ - v13.7.0
+ - v12.17.0
+-->
+
+#### `new SourceMap(payload)`
+
+* `payload` {Object}
+
+Creates a new `sourceMap` instance.
+
+`payload` is an object with keys matching the [Source map v3 format][]:
+
+* `file`: {string}
+* `version`: {number}
+* `sources`: {string[]}
+* `sourcesContent`: {string[]}
+* `names`: {string[]}
+* `mappings`: {string}
+* `sourceRoot`: {string}
+
+#### `sourceMap.payload`
+
+* Returns: {Object}
+
+Getter for the payload used to construct the [`SourceMap`][] instance.
+
+#### `sourceMap.findEntry(lineNumber, columnNumber)`
+
+* `lineNumber` {number}
+* `columnNumber` {number}
+* Returns: {Object}
+
+Given a line number and column number in the generated source file, returns
+an object representing the position in the original file. The object returned
+consists of the following keys:
+
+* generatedLine: {number}
+* generatedColumn: {number}
+* originalSource: {string}
+* originalLine: {number}
+* originalColumn: {number}
+
+[`createRequire()`]: #module_module_createrequire_filename
+[module wrapper]: modules_cjs.html#modules_cjs_the_module_wrapper
+[source map include directives]: https://sourcemaps.info/spec.html#h.lmz475t4mvbx
+[`--enable-source-maps`]: cli.html#cli_enable_source_maps
+[`NODE_V8_COVERAGE=dir`]: cli.html#cli_node_v8_coverage_dir
+[`Error.prepareStackTrace(error, trace)`]: https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+[`SourceMap`]: #module_class_module_sourcemap
+[Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej
diff --git a/doc/api/modules.md b/doc/api/modules.md
index 4d392dfb9b..4343efa4a0 100644
--- a/doc/api/modules.md
+++ b/doc/api/modules.md
@@ -953,189 +953,31 @@ in order to be used.
 
 ## The `Module` object
 
-<!-- YAML
-added: v0.3.7
--->
-
-* {Object}
-
-Provides general utility methods when interacting with instances of
-`Module`, the `module` variable often seen in file modules. Accessed
-via `require('module')`.
-
-### `module.builtinModules`
-<!-- YAML
-added:
-  - v9.3.0
-  - v8.10.0
-  - v6.13.0
--->
-
-* {string[]}
-
-A list of the names of all modules provided by Node.js. Can be used to verify
-if a module is maintained by a third party or not.
-
-`module` in this context isn't the same object that's provided
-by the [module wrapper][]. To access it, require the `Module` module:
-
-```js
-const builtin = require('module').builtinModules;
-```
-
-### `module.createRequire(filename)`
-<!-- YAML
-added: v12.2.0
--->
-
-* `filename` {string|URL} Filename to be used to construct the require
-  function. Must be a file URL object, file URL string, or absolute path
-  string.
-* Returns: {require} Require function
-
-```js
-import { createRequire } from 'module';
-const require = createRequire(import.meta.url);
-
-// sibling-module.js is a CommonJS module.
-const siblingModule = require('./sibling-module');
-```
-
-### `module.createRequireFromPath(filename)`
-<!-- YAML
-added: v10.12.0
-deprecated: v12.2.0
--->
-
-> Stability: 0 - Deprecated: Please use [`createRequire()`][] instead.
-
-* `filename` {string} Filename to be used to construct the relative require
-  function.
-* Returns: {require} Require function
-
-```js
-const { createRequireFromPath } = require('module');
-const requireUtil = createRequireFromPath('../src/utils/');
-
-// Require `../src/utils/some-tool`
-requireUtil('./some-tool');
-```
-
-### `module.syncBuiltinESMExports()`
-<!-- YAML
-added: v12.12.0
--->
-
-The `module.syncBuiltinESMExports()` method updates all the live bindings for
-builtin ES Modules to match the properties of the CommonJS exports. It does
-not add or remove exported names from the ES Modules.
+This section was moved to
+[Modules: `module` core module](modules_module.html#modules_module_the_module_object).
 
-```js
-const fs = require('fs');
-const { syncBuiltinESMExports } = require('module');
-
-fs.readFile = null;
-
-delete fs.readFileSync;
-
-fs.newAPI = function newAPI() {
-  // ...
-};
-
-syncBuiltinESMExports();
-
-import('fs').then((esmFS) => {
-  assert.strictEqual(esmFS.readFile, null);
-  assert.strictEqual('readFileSync' in fs, true);
-  assert.strictEqual(esmFS.newAPI, undefined);
-});
-```
+<!-- Anchors to make sure old links find a target -->
+* <a id="modules_module_builtinmodules" href="module.html#module_module_builtinmodules">`module.builtinModules`</a>
+* <a id="modules_module_createrequire_filename" href="module.html#module_module_createrequire_filename">`module.createRequire(filename)`</a>
+* <a id="modules_module_createrequirefrompath_filename" href="module.html#module_module_createrequirefrompath_filename">`module.createRequireFromPath(filename)`</a>
+* <a id="modules_module_syncbuiltinesmexports" href="module.html#module_module_syncbuiltinesmexports">`module.syncBuiltinESMExports()`</a>
 
 ## Source map v3 support
-<!-- YAML
-added: v12.17.0
--->
-
-> Stability: 1 - Experimental
-
-Helpers for interacting with the source map cache. This cache is
-populated when source map parsing is enabled and
-[source map include directives][] are found in a modules' footer.
-
-To enable source map parsing, Node.js must be run with the flag
-[`--enable-source-maps`][], or with code coverage enabled by setting
-[`NODE_V8_COVERAGE=dir`][].
-
-```js
-const { findSourceMap, SourceMap } = require('module');
-```
-
-### `module.findSourceMap(path[, error])`
-<!-- YAML
-added: v12.17.0
--->
-
-* `path` {string}
-* `error` {Error}
-* Returns: {module.SourceMap}
-
-`path` is the resolved path for the file for which a corresponding source map
-should be fetched.
-
-The `error` instance should be passed as the second parameter to `findSourceMap`
-in exceptional flows, e.g., when an overridden
-[`Error.prepareStackTrace(error, trace)`][] is invoked. Modules are not added to
-the module cache until they are successfully loaded, in these cases source maps
-will be associated with the `error` instance along with the `path`.
-
-### Class: `module.SourceMap`
-<!-- YAML
-added: v12.17.0
--->
-
-#### `new SourceMap(payload)`
-
-* `payload` {Object}
-
-Creates a new `sourceMap` instance.
-
-`payload` is an object with keys matching the [Source map v3 format][]:
-
-* `file`: {string}
-* `version`: {number}
-* `sources`: {string[]}
-* `sourcesContent`: {string[]}
-* `names`: {string[]}
-* `mappings`: {string}
-* `sourceRoot`: {string}
-
-#### `sourceMap.payload`
-
-* Returns: {Object}
-
-Getter for the payload used to construct the [`SourceMap`][] instance.
-
-#### `sourceMap.findEntry(lineNumber, columnNumber)`
-
-* `lineNumber` {number}
-* `columnNumber` {number}
-* Returns: {Object}
 
-Given a line number and column number in the generated source file, returns
-an object representing the position in the original file. The object returned
-consists of the following keys:
+This section was moved to
+[Modules: `module` core module](modules_module.html#modules_module_source_map_v3_support).
 
-* generatedLine: {number}
-* generatedColumn: {number}
-* originalSource: {string}
-* originalLine: {number}
-* originalColumn: {number}
+<!-- Anchors to make sure old links find a target -->
+* <a id="modules_module_findsourcemap_path_error" href="module.html#module_module_findsourcemap_path_error">`module.findSourceMap(path[, error])`</a>
+* <a id="modules_class_module_sourcemap" href="module.html#module_class_module_sourcemap">Class: `module.SourceMap`</a>
+  * <a id="modules_new_sourcemap_payload" href="module.html#module_new_sourcemap_payload">`new SourceMap(payload)`</a>
+  * <a id="modules_sourcemap_payload" href="module.html#module_sourcemap_payload">`sourceMap.payload`</a>
+  * <a id="modules_sourcemap_findentry_linenumber_columnnumber" href="module.html#module_sourcemap_findentry_linenumber_columnnumber">`sourceMap.findEntry(lineNumber, columnNumber)`</a>
 
 [GLOBAL_FOLDERS]: #modules_loading_from_the_global_folders
 [`Error`]: errors.html#errors_class_error
 [`__dirname`]: #modules_dirname
 [`__filename`]: #modules_filename
-[`createRequire()`]: #modules_module_createrequire_filename
 [`module` object]: #modules_the_module_object
 [`module.id`]: #modules_module_id
 [`module.children`]: #modules_module_children
@@ -1144,14 +986,7 @@ consists of the following keys:
 [an error]: errors.html#errors_err_require_esm
 [exports shortcut]: #modules_exports_shortcut
 [module resolution]: #modules_all_together
-[module wrapper]: #modules_the_module_wrapper
 [native addons]: addons.html
 [`require.main`]: #modules_require_main
-[source map include directives]: https://sourcemaps.info/spec.html#h.lmz475t4mvbx
-[`--enable-source-maps`]: cli.html#cli_enable_source_maps
-[`NODE_V8_COVERAGE=dir`]: cli.html#cli_node_v8_coverage_dir
-[`Error.prepareStackTrace(error, trace)`]: https://v8.dev/docs/stack-trace-api#customizing-stack-traces
-[`SourceMap`]: modules.html#modules_class_module_sourcemap
-[Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej
 [`package.json`]: packages.html#packages_node_js_package_json_field_definitions
 [`"main"`]: packages.html#packages_main