From 444362e0480c41a60d33918da3b8850a2a0d05d3 Mon Sep 17 00:00:00 2001 From: Jeremiah Senkpiel Date: Fri, 15 Dec 2017 16:49:36 -0500 Subject: [PATCH] doc: improve documentation.md Reworded some parts, inter-doc links. PR-URL: https://github.com/nodejs/node/pull/17702 Reviewed-By: Rich Trott Reviewed-By: Vse Mozhet Byt --- doc/api/documentation.md | 57 +++++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/doc/api/documentation.md b/doc/api/documentation.md index 802bf3613f9b55..f78d7c1f40b572 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -11,20 +11,16 @@ Where appropriate, property types, method arguments, and the arguments provided to event handlers are detailed in a list underneath the topic heading. -Every `.html` document has a corresponding `.json` document presenting -the same information in a structured manner. This feature is -experimental, and added for the benefit of IDEs and other utilities that -wish to do programmatic things with the documentation. - -Every `.html` and `.json` file is generated based on the corresponding -`.md` file in the `doc/api/` folder in Node.js's source tree. The -documentation is generated using the `tools/doc/generate.js` program. -The HTML template is located at `doc/template.html`. - +## Contributing If errors are found in this documentation, please [submit an issue][] or see [the contributing guide][] for directions on how to submit a patch. +Every file is generated based on the corresponding `.md` file in the +`doc/api/` folder in Node.js's source tree. The documentation is generated +using the `tools/doc/generate.js` program. An HTML template is located at +`doc/template.html`. + ## Stability Index @@ -53,40 +49,43 @@ is not recommended in production environments. Experimental features are not subject to the Node.js Semantic Versioning model. ``` -*Note*: Caution must be used when making use of `Experimental` features, -particularly within modules that may be used as dependencies (or dependencies -of dependencies) within a Node.js application. End users may not be aware that -experimental features are being used, and therefore may experience unexpected -failures or behavioral changes when changes occur. To help avoid such surprises, -`Experimental` features may require a command-line flag to explicitly enable -them, or may cause a process warning to be emitted. By default, such warnings -are printed to `stderr` and may be handled by attaching a listener to the -`process.on('warning')` event. - ```txt Stability: 2 - Stable The API has proven satisfactory. Compatibility with the npm ecosystem is a high priority, and will not be broken unless absolutely necessary. ``` +*Note*: Caution must be used when making use of `Experimental` features, +particularly within modules that may be used as dependencies (or dependencies +of dependencies) within a Node.js application. End users may not be aware that +experimental features are being used, and therefore 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 +explicitly enable them, or may cause a process warning to be emitted. +By default, such warnings are printed to [`stderr`][] and may be handled by +attaching a listener to the [`process.on('warning')`][] event. + ## JSON Output + > Stability: 1 - Experimental -Every HTML file in the markdown has a corresponding JSON file with the -same data. - -This feature was added in Node.js v0.6.12. It is experimental. +Every `.html` document has a corresponding `.json` document presenting +the same information in a structured manner. This feature is +experimental, and added for the benefit of IDEs and other utilities that +wish to do programmatic things with the documentation. ## Syscalls and man pages System calls like open(2) and read(2) define the interface between user programs and the underlying operating system. Node functions which simply wrap a syscall, -like `fs.open()`, will document that. The docs link to the corresponding man +like [`fs.open()`][], will document that. The docs link to the corresponding man pages (short for manual pages) which describe how the syscalls work. -**Note:** some syscalls, like lchown(2), are BSD-specific. That means, for -example, that `fs.lchown()` only works on macOS and other BSD-derived systems, +Some syscalls, like lchown(2), are BSD-specific. That means, for +example, that [`fs.lchown()`][] only works on macOS and other BSD-derived systems, and is not available on Linux. Most Unix syscalls have Windows equivalents, but behavior may differ on Windows @@ -96,3 +95,7 @@ issue 4760](https://github.com/nodejs/node/issues/4760). [submit an issue]: https://github.com/nodejs/node/issues/new [the contributing guide]: https://github.com/nodejs/node/blob/master/CONTRIBUTING.md +[`stderr`]: process.html#process_process_stderr +[`process.on('warning')`]: process.html#process_event_warning +[`fs.open()`]: fs.html#fs_fs_open_path_flags_mode_callback +[`fs.lchown()`]: fs.html#fs_fs_lchown_path_uid_gid_callback