From 524c07873cbf370ca46cd92917feb779e9ef485d Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sun, 23 Mar 2025 16:58:20 +0100 Subject: [PATCH] doc: make stability labels more consistent PR-URL: https://github.com/nodejs/node/pull/57516 Reviewed-By: Luigi Pinca Reviewed-By: Matteo Collina --- doc/api/assert.md | 2 - doc/api/buffer.md | 2 - doc/api/cli.md | 36 ++------------- doc/api/diagnostics_channel.md | 12 ----- doc/api/esm.md | 4 -- doc/api/events.md | 4 -- doc/api/globals.md | 80 +++++++++++++++++++++++++++++++--- doc/api/module.md | 6 --- doc/api/permissions.md | 2 +- doc/api/test.md | 2 - doc/api/typescript.md | 2 - doc/api/url.md | 6 --- doc/api/zlib.md | 8 ---- doc/api_assets/style.css | 7 +++ tools/doc/html.mjs | 31 ++++++++++++- 15 files changed, 116 insertions(+), 88 deletions(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 3fb67cb8d1e..4e451230bc4 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -2600,8 +2600,6 @@ changes: description: partialDeepStrictEqual is now Stable. Previously, it had been Experimental. --> -> Stability: 2 - Stable - * `actual` {any} * `expected` {any} * `message` {string|Error} diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 0e1074a8185..f9fd729b98a 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -5358,8 +5358,6 @@ instance. deprecated: v6.0.0 --> -> Stability: 0 - Deprecated: Use [`Buffer.allocUnsafeSlow()`][] instead. - * `size` {integer} The desired length of the new `SlowBuffer`. See [`Buffer.allocUnsafeSlow()`][]. diff --git a/doc/api/cli.md b/doc/api/cli.md index 63e68244e75..d5c86fd65db 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -61,6 +61,8 @@ changes: Node.js options as well, in addition to V8 options. --> +> Stability: 2 - Stable + All options, including V8 options, allow words to be separated by both dashes (`-`) or underscores (`_`). For example, `--pending-deprecation` is equivalent to `--pending_deprecation`. @@ -201,8 +203,6 @@ changes: description: Paths delimited by comma (`,`) are no longer allowed. --> -> Stability: 2 - Stable. - This flag configures file system read permissions using the [Permission Model][]. @@ -248,8 +248,6 @@ changes: description: Paths delimited by comma (`,`) are no longer allowed. --> -> Stability: 2 - Stable. - This flag configures file system write permissions using the [Permission Model][]. @@ -457,8 +455,6 @@ changes: description: The flag is no longer experimental. --> -> Stability: 2 - Stable - Provide custom [conditional exports][] resolution conditions. Any number of custom string condition names are permitted. @@ -484,8 +480,6 @@ changes: description: The `--cpu-prof` flags are now stable. --> -> Stability: 2 - Stable - Starts the V8 CPU profiler on start up, and writes the CPU profile to disk before exit. @@ -522,8 +516,6 @@ changes: description: The `--cpu-prof` flags are now stable. --> -> Stability: 2 - Stable - Specify the directory where the CPU profiles generated by `--cpu-prof` will be placed. @@ -542,8 +534,6 @@ changes: description: The `--cpu-prof` flags are now stable. --> -> Stability: 2 - Stable - Specify the sampling interval in microseconds for the CPU profiles generated by `--cpu-prof`. The default is 1000 microseconds. @@ -559,8 +549,6 @@ changes: description: The `--cpu-prof` flags are now stable. --> -> Stability: 2 - Stable - Specify the file name of the CPU profile generated by `--cpu-prof`. ### `--diagnostic-dir=directory` @@ -1295,8 +1283,6 @@ changes: description: The `--heap-prof` flags are now stable. --> -> Stability: 2 - Stable - Starts the V8 heap profiler on start up, and writes the heap profile to disk before exit. @@ -1324,8 +1310,6 @@ changes: description: The `--heap-prof` flags are now stable. --> -> Stability: 2 - Stable - Specify the directory where the heap profiles generated by `--heap-prof` will be placed. @@ -1344,8 +1328,6 @@ changes: description: The `--heap-prof` flags are now stable. --> -> Stability: 2 - Stable - Specify the average sampling interval in bytes for the heap profiles generated by `--heap-prof`. The default is 512 \* 1024 bytes. @@ -1361,8 +1343,6 @@ changes: description: The `--heap-prof` flags are now stable. --> -> Stability: 2 - Stable - Specify the file name of the heap profile generated by `--heap-prof`. ### `--heapsnapshot-near-heap-limit=max_count` @@ -1695,8 +1675,6 @@ requiring a native C++ addon will fail and throw an exception. added: REPLACEME --> -> Stability: 2 - Stable - Disables the use of [`AsyncLocalStorage`][] backed by `AsyncContextFrame` and uses the prior implementation which relied on async\_hooks. The previous model is retained for compatibility with Electron and for cases where the context @@ -1928,8 +1906,6 @@ changes: description: Permission Model is now stable. --> -> Stability: 2 - Stable. - Enable the Permission Model for current process. When enabled, the following permissions are restricted: @@ -2244,8 +2220,6 @@ changes: `PATH` environment variable accordingly. --> -> Stability: 2 - Stable - This runs a specified command from a package.json's `"scripts"` object. If a missing `"command"` is provided, it will list the available scripts. @@ -3053,8 +3027,6 @@ changes: description: Test runner now supports running in watch mode. --> -> Stability: 2 - Stable - Starts Node.js in watch mode. When in watch mode, changes in the watched files cause the Node.js process to restart. @@ -3083,8 +3055,6 @@ changes: description: Watch mode is now stable. --> -> Stability: 2 - Stable - Starts Node.js in watch mode and specifies what paths to watch. When in watch mode, changes in the watched paths cause the Node.js process to restart. @@ -3127,6 +3097,8 @@ instances. ## Environment variables +> Stability: 2 - Stable + ### `FORCE_COLOR=[1, 2, 3]` The `FORCE_COLOR` environment variable is used to diff --git a/doc/api/diagnostics_channel.md b/doc/api/diagnostics_channel.md index 715171ddb42..eb5aad6efc2 100644 --- a/doc/api/diagnostics_channel.md +++ b/doc/api/diagnostics_channel.md @@ -635,8 +635,6 @@ added: - v18.19.0 --> -> Stability: 1 - Experimental - * `subscribers` {Object} Set of [TracingChannel Channels][] subscribers * `start` {Function} The [`start` event][] subscriber * `end` {Function} The [`end` event][] subscriber @@ -704,8 +702,6 @@ added: - v18.19.0 --> -> Stability: 1 - Experimental - * `subscribers` {Object} Set of [TracingChannel Channels][] subscribers * `start` {Function} The [`start` event][] subscriber * `end` {Function} The [`end` event][] subscriber @@ -775,8 +771,6 @@ added: - v18.19.0 --> -> Stability: 1 - Experimental - * `fn` {Function} Function to wrap a trace around * `context` {Object} Shared object to correlate events through * `thisArg` {any} The receiver to be used for the function call @@ -826,8 +820,6 @@ added: - v18.19.0 --> -> Stability: 1 - Experimental - * `fn` {Function} Promise-returning function to wrap a trace around * `context` {Object} Shared object to correlate trace events through * `thisArg` {any} The receiver to be used for the function call @@ -880,8 +872,6 @@ added: - v18.19.0 --> -> Stability: 1 - Experimental - * `fn` {Function} callback using function to wrap a trace around * `position` {number} Zero-indexed argument position of expected callback (defaults to last argument if `undefined` is passed) @@ -985,8 +975,6 @@ added: - v20.13.0 --> -> Stability: 1 - Experimental - * Returns: {boolean} `true` if any of the individual channels has a subscriber, `false` if not. diff --git a/doc/api/esm.md b/doc/api/esm.md index cedcb7cb94a..a34c8384d64 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -279,8 +279,6 @@ changes: description: Switch from Import Assertions to Import Attributes. --> -> Stability: 2 - Stable - [Import attributes][Import Attributes MDN] are an inline syntax for module import statements to pass on more information alongside the module specifier. @@ -648,8 +646,6 @@ changes: description: JSON modules are no longer experimental. --> -> Stability: 2 - Stable - JSON files can be referenced by `import`: ```js diff --git a/doc/api/events.md b/doc/api/events.md index e16054bcc58..be935384bf5 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -2444,8 +2444,6 @@ changes: description: No longer behind `--experimental-global-customevent` CLI flag. --> -> Stability: 2 - Stable - * Extends: {Event} The `CustomEvent` object is an adaptation of the [`CustomEvent` Web API][]. @@ -2465,8 +2463,6 @@ changes: description: CustomEvent is now stable. --> -> Stability: 2 - Stable - * Type: {any} Returns custom data passed when initializing. Read-only. diff --git a/doc/api/globals.md b/doc/api/globals.md index 8897d637be5..3eb5a7b24e2 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -31,6 +31,8 @@ changes: description: No longer experimental. --> +> Stability: 2 - Stable + A utility class used to signal cancelation in selected `Promise`-based APIs. @@ -230,6 +232,8 @@ If `abortSignal.aborted` is `true`, throws `abortSignal.reason`. added: v18.0.0 --> +> Stability: 2 - Stable + See {Blob}. @@ -240,6 +244,8 @@ See {Blob}. added: v0.1.103 --> +> Stability: 2 - Stable + * {Function} @@ -282,6 +288,8 @@ Global alias for [`buffer.atob()`][]. added: v18.0.0 --> +> Stability: 2 - Stable + See {BroadcastChannel}. ## `btoa(data)` @@ -300,6 +308,8 @@ Global alias for [`buffer.btoa()`][]. added: v0.9.1 --> +> Stability: 2 - Stable + [`clearImmediate`][] is described in the [timers][] section. @@ -310,6 +320,8 @@ added: v0.9.1 added: v0.0.1 --> +> Stability: 2 - Stable + [`clearInterval`][] is described in the [timers][] section. @@ -320,6 +332,8 @@ added: v0.0.1 added: v0.0.1 --> +> Stability: 2 - Stable + [`clearTimeout`][] is described in the [timers][] section. @@ -330,6 +344,8 @@ added: v0.0.1 added: v23.0.0 --> +> Stability: 2 - Stable + The `CloseEvent` class. See [`CloseEvent`][] for more details. @@ -355,6 +371,8 @@ A browser-compatible implementation of [`CompressionStream`][]. added: v0.1.100 --> +> Stability: 2 - Stable + * {Object} @@ -388,7 +406,7 @@ changes: description: No longer behind `--experimental-global-webcrypto` CLI flag. --> -> Stability: 2 - Stable. +> Stability: 2 - Stable A browser-compatible implementation of {Crypto}. This global is available only if the Node.js binary was compiled with including support for the @@ -409,7 +427,7 @@ changes: description: No longer behind `--experimental-global-webcrypto` CLI flag. --> -> Stability: 2 - Stable. +> Stability: 2 - Stable A browser-compatible implementation of the [Web Crypto API][]. @@ -428,7 +446,7 @@ changes: description: No longer behind `--experimental-global-webcrypto` CLI flag. --> -> Stability: 2 - Stable. +> Stability: 2 - Stable A browser-compatible implementation of {CryptoKey}. This global is available only if the Node.js binary was compiled with including support for the @@ -482,6 +500,8 @@ changes: description: No longer experimental. --> +> Stability: 2 - Stable + A browser-compatible implementation of the `Event` class. See @@ -510,6 +530,8 @@ changes: description: No longer experimental. --> +> Stability: 2 - Stable + A browser-compatible implementation of the `EventTarget` class. See @@ -545,6 +567,8 @@ A browser-compatible implementation of the [`fetch()`][] function. added: v20.0.0 --> +> Stability: 2 - Stable + See {File}. @@ -630,6 +654,8 @@ of a server, it is shared across all users and requests. added: v15.0.0 --> +> Stability: 2 - Stable + The `MessageChannel` class. See [`MessageChannel`][] for more details. @@ -640,6 +666,8 @@ The `MessageChannel` class. See [`MessageChannel`][] for more details. added: v15.0.0 --> +> Stability: 2 - Stable + The `MessageEvent` class. See [`MessageEvent`][] for more details. @@ -650,6 +678,8 @@ The `MessageEvent` class. See [`MessageEvent`][] for more details. added: v15.0.0 --> +> Stability: 2 - Stable + The `MessagePort` class. See [`MessagePort`][] for more details. @@ -772,6 +802,8 @@ console.log(`The user-agent is ${navigator.userAgent}`); // Prints "Node.js/21" added: v19.0.0 --> +> Stability: 2 - Stable + The `PerformanceEntry` class. See [`PerformanceEntry`][] for more details. @@ -782,6 +814,8 @@ The `PerformanceEntry` class. See [`PerformanceEntry`][] for more details. added: v19.0.0 --> +> Stability: 2 - Stable + The `PerformanceMark` class. See [`PerformanceMark`][] for more details. @@ -792,6 +826,8 @@ The `PerformanceMark` class. See [`PerformanceMark`][] for more details. added: v19.0.0 --> +> Stability: 2 - Stable + The `PerformanceMeasure` class. See [`PerformanceMeasure`][] for more details. @@ -802,6 +838,8 @@ The `PerformanceMeasure` class. See [`PerformanceMeasure`][] for more details. added: v19.0.0 --> +> Stability: 2 - Stable + The `PerformanceObserver` class. See [`PerformanceObserver`][] for more details. @@ -812,6 +850,8 @@ The `PerformanceObserver` class. See [`PerformanceObserver`][] for more details. added: v19.0.0 --> +> Stability: 2 - Stable + The `PerformanceObserverEntryList` class. See @@ -823,6 +863,8 @@ The `PerformanceObserverEntryList` class. See added: v19.0.0 --> +> Stability: 2 - Stable + The `PerformanceResourceTiming` class. See [`PerformanceResourceTiming`][] for @@ -834,6 +876,8 @@ more details. added: v16.0.0 --> +> Stability: 2 - Stable + The [`perf_hooks.performance`][] object. ## `process` @@ -842,6 +886,8 @@ The [`perf_hooks.performance`][] object. added: v0.1.7 --> +> Stability: 2 - Stable + * {Object} @@ -854,6 +900,8 @@ The process object. See the [`process` object][] section. added: v11.0.0 --> +> Stability: 2 - Stable + * `callback` {Function} Function to be queued. @@ -1022,6 +1070,8 @@ the currently running process, and is not shared between workers. added: v0.9.1 --> +> Stability: 2 - Stable + [`setImmediate`][] is described in the [timers][] section. @@ -1032,6 +1082,8 @@ added: v0.9.1 added: v0.0.1 --> +> Stability: 2 - Stable + [`setInterval`][] is described in the [timers][] section. @@ -1042,6 +1094,8 @@ added: v0.0.1 added: v0.0.1 --> +> Stability: 2 - Stable + [`setTimeout`][] is described in the [timers][] section. @@ -1063,6 +1117,8 @@ A browser-compatible implementation of [`Storage`][]. Enable this API with the added: v17.0.0 --> +> Stability: 2 - Stable + The WHATWG [`structuredClone`][] method. @@ -1079,7 +1135,7 @@ changes: description: No longer behind `--experimental-global-webcrypto` CLI flag. --> -> Stability: 2 - Stable. +> Stability: 2 - Stable A browser-compatible implementation of {SubtleCrypto}. This global is available only if the Node.js binary was compiled with including support for the @@ -1091,6 +1147,8 @@ only if the Node.js binary was compiled with including support for the added: v17.0.0 --> +> Stability: 2 - Stable + The WHATWG `DOMException` class. See [`DOMException`][] for more details. @@ -1101,6 +1159,8 @@ The WHATWG `DOMException` class. See [`DOMException`][] for more details. added: v11.0.0 --> +> Stability: 2 - Stable + The WHATWG `TextDecoder` class. See the [`TextDecoder`][] section. @@ -1123,6 +1183,8 @@ A browser-compatible implementation of [`TextDecoderStream`][]. added: v11.0.0 --> +> Stability: 2 - Stable + The WHATWG `TextEncoder` class. See the [`TextEncoder`][] section. @@ -1169,6 +1231,8 @@ A browser-compatible implementation of [`TransformStreamDefaultController`][]. added: v10.0.0 --> +> Stability: 2 - Stable + The WHATWG `URL` class. See the [`URL`][] section. @@ -1179,6 +1243,8 @@ The WHATWG `URL` class. See the [`URL`][] section. added: REPLACEME --> +> Stability: 1 - Experimental + The WHATWG `URLPattern` class. See the [`URLPattern`][] section. @@ -1189,6 +1255,8 @@ The WHATWG `URLPattern` class. See the [`URLPattern`][] section. added: v10.0.0 --> +> Stability: 2 - Stable + The WHATWG `URLSearchParams` class. See the [`URLSearchParams`][] section. @@ -1199,6 +1267,8 @@ The WHATWG `URLSearchParams` class. See the [`URLSearchParams`][] section. added: v8.0.0 --> +> Stability: 2 - Stable + * {Object} @@ -1222,7 +1292,7 @@ changes: description: No longer behind `--experimental-websocket` CLI flag. --> -> Stability: 2 - Stable. +> Stability: 2 - Stable A browser-compatible implementation of [`WebSocket`][]. Disable this API with the [`--no-experimental-websocket`][] CLI flag. diff --git a/doc/api/module.md b/doc/api/module.md index 69e34f1cdcf..5729780a70a 100644 --- a/doc/api/module.md +++ b/doc/api/module.md @@ -1034,9 +1034,6 @@ changes: description: Add support for import assertions. --> -> Stability: 1.2 - Release candidate (asynchronous version) -> Stability: 1.1 - Active development (synchronous version) - * `specifier` {string} * `context` {Object} * `conditions` {string\[]} Export conditions of the relevant `package.json` @@ -1150,9 +1147,6 @@ changes: its return. --> -> Stability: 1.2 - Release candidate (asynchronous version) -> Stability: 1.1 - Active development (synchronous version) - * `url` {string} The URL returned by the `resolve` chain * `context` {Object} * `conditions` {string\[]} Export conditions of the relevant `package.json` diff --git a/doc/api/permissions.md b/doc/api/permissions.md index d72adbb324e..f912cb62862 100644 --- a/doc/api/permissions.md +++ b/doc/api/permissions.md @@ -40,7 +40,7 @@ changes: description: This feature is no longer experimental. --> -> Stability: 2 - Stable. +> Stability: 2 - Stable The Node.js Permission Model is a mechanism for restricting access to specific resources during execution. diff --git a/doc/api/test.md b/doc/api/test.md index a6cb00cd362..1403c621e80 100644 --- a/doc/api/test.md +++ b/doc/api/test.md @@ -2227,8 +2227,6 @@ changes: description: The Mock Timers is now stable. --> -> Stability: 2 - Stable - Mocking timers is a technique commonly used in software testing to simulate and control the behavior of timers, such as `setInterval` and `setTimeout`, without actually waiting for the specified time intervals. diff --git a/doc/api/typescript.md b/doc/api/typescript.md index cf26b2cbe3f..bac78a775f1 100644 --- a/doc/api/typescript.md +++ b/doc/api/typescript.md @@ -55,8 +55,6 @@ To use TypeScript with full support for all TypeScript features, including added: v22.6.0 --> -> Stability: 1.1 - Active development - By default Node.js will execute TypeScript files that contains only erasable TypeScript syntax. Node.js will replace TypeScript syntax with whitespace, diff --git a/doc/api/url.md b/doc/api/url.md index 7a4bece9a48..c519331432a 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -1564,8 +1564,6 @@ changes: description: The Legacy URL API is deprecated. Use the WHATWG URL API. --> -> Stability: 3 - Legacy: Use the WHATWG URL API instead. - The legacy `urlObject` (`require('node:url').Url` or `import { Url } from 'node:url'`) is created and returned by the `url.parse()` function. @@ -1693,8 +1691,6 @@ changes: times. --> -> Stability: 3 - Legacy: Use the WHATWG URL API instead. - * `urlObject` {Object|string} A URL object (as returned by `url.parse()` or constructed otherwise). If a string, it is converted to an object by passing it to `url.parse()`. @@ -1855,8 +1851,6 @@ changes: contains a hostname. --> -> Stability: 3 - Legacy: Use the WHATWG URL API instead. - * `from` {string} The base URL to use if `to` is a relative URL. * `to` {string} The target URL to resolve. diff --git a/doc/api/zlib.md b/doc/api/zlib.md index 91f6406c9e2..664aaf298f7 100644 --- a/doc/api/zlib.md +++ b/doc/api/zlib.md @@ -733,8 +733,6 @@ streams: #### Flush operations -> Stability: 1 - Experimental - The following values are valid flush operations for Zstd-based streams: * `zlib.constants.ZSTD_e_continue` (default for all operations) @@ -743,8 +741,6 @@ The following values are valid flush operations for Zstd-based streams: #### Compressor options -> Stability: 1 - Experimental - There are several options that can be set on Zstd encoders, affecting compression efficiency and speed. Both the keys and the values can be accessed as properties of the `zlib.constants` object. @@ -757,16 +753,12 @@ The most important options are: #### Pledged Source Size -> Stability: 1 - Experimental - It's possible to specify the expected total size of the uncompressed input via `opts.pledgedSrcSize`. If the size doesn't match at the end of the input, compression will fail with the code `ZSTD_error_srcSize_wrong`. #### Decompressor options -> Stability: 1 - Experimental - These advanced options are available for controlling decompression: * `ZSTD_d_windowLogMax` diff --git a/doc/api_assets/style.css b/doc/api_assets/style.css index 9f56028d091..e40fc2305ea 100644 --- a/doc/api_assets/style.css +++ b/doc/api_assets/style.css @@ -294,6 +294,10 @@ li.picker-header a span { margin: 0 0 1rem; padding: 1rem; line-height: 1.5; + + position: sticky; + top: 3rem; + z-index: 1; } .api_stability * { @@ -827,6 +831,9 @@ kbd { position: relative; top: 0; } + .api_stability { + top: 0; + } } @media not screen, (max-height: 1000px) { diff --git a/tools/doc/html.mjs b/tools/doc/html.mjs index d61d335c7b8..0ab54d67865 100644 --- a/tools/doc/html.mjs +++ b/tools/doc/html.mjs @@ -216,6 +216,22 @@ export function preprocessElements({ filename }) { visit(tree, null, (node, index, parent) => { if (node.type === 'heading') { headingIndex = index; + if (heading) { + node.parentHeading = heading; + for (let d = heading.depth; d >= node.depth; d--) { + node.parentHeading = node.parentHeading.parentHeading; + } + + if (heading.depth > 2 || node.depth > 2) { + const isNonWrapped = node.depth > 2; // For depth of 1 and 2, there's already a wrapper. + parent.children.splice(index++, 0, { + type: 'html', + value: + ``.repeat(heading.depth - node.depth + isNonWrapped) + + (isNonWrapped ? '
' : ''), + }); + } + } heading = node; } else if (node.type === 'code') { if (!node.lang) { @@ -286,13 +302,20 @@ export function preprocessElements({ filename }) { if (heading && isStabilityIndex) { heading.stability = number; + for (let h = heading; h != null; h = h.parentHeading) { + if (!h.hasStabilityIndexElement) continue; + if (h.stability === number && h.explication === explication) { + throw new Error(`Duplicate stability index at ${filename}:${node.position.start.line}, it already inherits it from a parent heading ${filename}:${h.position.start.line}`); + } else break; + } + heading.hasStabilityIndexElement = true; + heading.explication = explication; headingIndex = -1; - heading = null; } // Do not link to the section we are already in. const noLinking = filename.includes('documentation') && - heading !== null && heading.children[0].value === 'Stability index'; + !heading.hasStabilityIndexElement && heading.children[0].value === 'Stability index'; // Collapse blockquote and paragraph into a single node node.type = 'paragraph'; @@ -316,6 +339,10 @@ export function preprocessElements({ filename }) { node.children.push({ type: 'html', value: '
' }); } } + + // In case we've inserted/removed node(s) before the current one, we need + // to make sure we're not visiting the same node again or skipping one. + return [true, index + 1]; }); }; }