doc: correct customization hook types & clarify descriptions

doc/api/module.md

@@ -1034,13 +1034,14 @@ changes:
 * `nextResolve` {Function} The subsequent `resolve` hook in the chain, or the
  Node.js default `resolve` hook after the last user-supplied `resolve` hook
  * `specifier` {string}
- * `context` {Object}
+ * `context` {Object|undefined} When omitted, the defaults are provided. When provided, defaults
+ are merged in with preference to the provided properties.
 * Returns: {Object|Promise} The asynchronous version takes either an object containing the
  following properties, or a `Promise` that will resolve to such an object. The
  synchronous version only accepts an object returned synchronously.
- * `format` {string|null|undefined} A hint to the load hook (it might be
- ignored)
- `'builtin' | 'commonjs' | 'json' | 'module' | 'wasm'`
+ * `format` {string|null|undefined} A hint to the `load` hook (it might be ignored). It can be a
+ module format (such as `'commonjs'` or `'module'`) or an arbitrary value like `'css'` or
+ `'yaml'`.
  * `importAttributes` {Object|undefined} The import attributes to use when
  caching the module (optional; if excluded the input will be used)
  * `shortCircuit` {undefined|boolean} A signal that this hook intends to
@@ -1143,12 +1144,13 @@ changes:
 * `context` {Object}
  * `conditions` {string\[]} Export conditions of the relevant `package.json`
  * `format` {string|null|undefined} The format optionally supplied by the
- `resolve` hook chain
+ `resolve` hook chain. This can be any string value, not necessarily a valid return value.
  * `importAttributes` {Object}
 * `nextLoad` {Function} The subsequent `load` hook in the chain, or the
  Node.js default `load` hook after the last user-supplied `load` hook
  * `url` {string}
- * `context` {Object}
+ * `context` {Object|undefined} When omitted, defaults are provided. When provided, defaults are
+ merged in with preference to the provided properties.
 * Returns: {Object|Promise} The asynchronous version takes either an object containing the
  following properties, or a `Promise` that will resolve to such an object. The
  synchronous version only accepts an object returned synchronously.

lib/internal/modules/customization_hooks.js

@@ -25,17 +25,40 @@ let debug = require('internal/util/debuglog').debuglog('module_hooks', (fn) => {
  debug = fn;
 });
 
-/** @typedef {import('internal/modules/cjs/loader.js').Module} Module */
 /**
- * @typedef {(specifier: string, context: ModuleResolveContext, nextResolve: ResolveHook)
- * => ModuleResolveResult} ResolveHook
- * @typedef {(url: string, context: ModuleLoadContext, nextLoad: LoadHook)
- * => ModuleLoadResult} LoadHook
+ * @typedef {import('internal/modules/cjs/loader.js').Module} Module
+ */
+/**
+ * @typedef {(
+ * specifier: string,
+ * context: Partial<ModuleResolveContext>,
+ * ) => ModuleResolveResult
+ * } NextResolve
+ * @typedef {(
+ * specifier: string,
+ * context: ModuleResolveContext,
+ * nextResolve: NextResolve,
+ * ) => ModuleResolveResult
+ * } ResolveHook
+ * @typedef {(
+ * url: string,
+ * context: Partial<ModuleLoadContext>,
+ * ) => ModuleLoadResult
+ * } NextLoad
+ * @typedef {(
+ * url: string,
+ * context: ModuleLoadContext,
+ * nextLoad: NextLoad,
+ * ) => ModuleLoadResult
+ * } LoadHook
  */
 
 // Use arrays for better insertion and iteration performance, we don't care
 // about deletion performance as much.
+
+/** @type {ResolveHook[]} */
 const resolveHooks = [];
+/** @type {LoadHook[]} */
 const loadHooks = [];
 const hookId = Symbol('kModuleHooksIdKey');
 let nextHookId = 0;