diff options
author | Rich Trott <rtrott@gmail.com> | 2019-05-28 08:59:03 +0300 |
---|---|---|
committer | Rich Trott <rtrott@gmail.com> | 2019-05-30 10:48:20 +0300 |
commit | ff4a71ccc34ab122a0a78ac7bc1c5c57b7d14867 (patch) | |
tree | ffe938a7cc24884aa4cacc20110558b1c5e4deb6 /doc/api/documentation.md | |
parent | 76cffddf82603a6060840d5c20064b7aa0a5e9dd (diff) |
doc: revise additional Experimental status text
Clarify and simplify material urging caution with Experimental features.
PR-URL: https://github.com/nodejs/node/pull/27931
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Diffstat (limited to 'doc/api/documentation.md')
-rw-r--r-- | doc/api/documentation.md | 17 |
1 files changed, 6 insertions, 11 deletions
diff --git a/doc/api/documentation.md b/doc/api/documentation.md index 2d027101080..b441e9806fe 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -37,15 +37,11 @@ The stability indices are as follows: > Stability: 2 - Stable. Compatibility with the npm ecosystem is a high > priority. -Use caution when making use of `Experimental` features, particularly -within modules that are dependencies (or dependencies of -dependencies) within a Node.js application. End users may not be aware that -experimental features are being used, and may experience unexpected -failures or behavior changes when API modifications occur. To help avoid such -surprises, `Experimental` features may require a command-line flag to -enable them, or may emit a process warning. -By default, such warnings are printed to [`stderr`][] and may be handled by -attaching a listener to the [`'warning'`][] event. +Use caution when making use of Experimental features, particularly within +modules. End users may not be aware that experimental features are being used. +Bugs or behavior changes may surprise end users when Experimental API +modifications occur. To avoid surprises, use of an Experimental feature may need +a command-line flag. Experimental features may also emit a [warning][]. ## JSON Output <!-- YAML @@ -68,9 +64,8 @@ relative to Linux and macOS. For an example of the subtle ways in which it's sometimes impossible to replace Unix syscall semantics on Windows, see [Node.js issue 4760](https://github.com/nodejs/node/issues/4760). -[`'warning'`]: process.html#process_event_warning [`fs.open()`]: fs.html#fs_fs_open_path_flags_mode_callback -[`stderr`]: process.html#process_process_stderr [the contributing guide]: https://github.com/nodejs/node/blob/master/CONTRIBUTING.md [the issue tracker]: https://github.com/nodejs/node/issues/new [V8 JavaScript engine]: https://v8.dev/ +[warning]: process.html#process_event_warning |