From f2e31eb67f696648de845f18624facf3d62d2ed2 Mon Sep 17 00:00:00 2001 From: Jeremiah Senkpiel Date: Fri, 15 Dec 2017 16:49:36 -0500 Subject: [PATCH 1/4] 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 From 934490b3f6e7368b5786f43964cf8001208f4e04 Mon Sep 17 00:00:00 2001 From: Jeremiah Senkpiel Date: Fri, 15 Dec 2017 16:50:08 -0500 Subject: [PATCH 2/4] doc: fix fs.existsSync description Also works on directories. PR-URL: https://github.com/nodejs/node/pull/17702 Reviewed-By: Rich Trott Reviewed-By: Vse Mozhet Byt --- doc/api/fs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index fb8d246f03d845..3a49e658e79f51 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -1099,7 +1099,7 @@ changes: * `path` {string|Buffer|URL} Synchronous version of [`fs.exists()`][]. -Returns `true` if the file exists, `false` otherwise. +Returns `true` if the path exists, `false` otherwise. Note that `fs.exists()` is deprecated, but `fs.existsSync()` is not. (The `callback` parameter to `fs.exists()` accepts parameters that are From 606ff7c6f2cb8ab36bdbbe782eaef66f83a42f08 Mon Sep 17 00:00:00 2001 From: Jeremiah Senkpiel Date: Fri, 15 Dec 2017 16:50:32 -0500 Subject: [PATCH 3/4] doc: adjust TTY wording & add inter-doc links PR-URL: https://github.com/nodejs/node/pull/17702 Reviewed-By: Rich Trott Reviewed-By: Vse Mozhet Byt --- doc/api/tty.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/doc/api/tty.md b/doc/api/tty.md index f91a37a12095e5..8b757c0f02751a 100644 --- a/doc/api/tty.md +++ b/doc/api/tty.md @@ -12,9 +12,9 @@ However, it can be accessed using: const tty = require('tty'); ``` -When Node.js detects that it is being run inside a text terminal ("TTY") -context, the `process.stdin` will, by default, be initialized as an instance of -`tty.ReadStream` and both `process.stdout` and `process.stderr` will, by +When Node.js detects that it is being run with a text terminal ("TTY") +attached, [`process.stdin`][] will, by default, be initialized as an instance of +`tty.ReadStream` and both [`process.stdout`][] and [`process.stderr`][] will, by default be instances of `tty.WriteStream`. The preferred method of determining whether Node.js is being run within a TTY context is to check that the value of the `process.stdout.isTTY` property is `true`: @@ -27,15 +27,16 @@ false ``` In most cases, there should be little to no reason for an application to -create instances of the `tty.ReadStream` and `tty.WriteStream` classes. +manually create instances of the `tty.ReadStream` and `tty.WriteStream` +classes. ## Class: tty.ReadStream -The `tty.ReadStream` class is a subclass of `net.Socket` that represents the -readable side of a TTY. In normal circumstances `process.stdin` will be the +The `tty.ReadStream` class is a subclass of [`net.Socket`][] that represents the +readable side of a TTY. In normal circumstances [`process.stdin`][] will be the only `tty.ReadStream` instance in a Node.js process and there should be no reason to create additional instances. @@ -52,7 +53,7 @@ raw device. Defaults to `false`. added: v0.5.8 --> -A `boolean` that is always `true`. +A `boolean` that is always `true` for `tty.ReadStream` instances. ### readStream.setRawMode(mode) The `tty.WriteStream` class is a subclass of `net.Socket` that represents the -writable side of a TTY. In normal circumstances, `process.stdout` and -`process.stderr` will be the only `tty.WriteStream` instances created for a +writable side of a TTY. In normal circumstances, [`process.stdout`][] and +[`process.stderr`][] will be the only `tty.WriteStream` instances created for a Node.js process and there should be no reason to create additional instances. ### Event: 'resize' @@ -130,3 +131,8 @@ added: v0.5.8 The `tty.isatty()` method returns `true` if the given `fd` is associated with a TTY and `false` if it is not, including whenever `fd` is not a non-negative integer. + +[`net.Socket`]: net.html#net_class_net_socket +[`process.stdin`]: process.html#process_process_stdin +[`process.stdout`]: process.html#process_process_stdout +[`process.stderr`]: process.html#process_process_stderr From ce38c49fb8ec3a1c0a84624914b5bed57fadbbfe Mon Sep 17 00:00:00 2001 From: Jeremiah Senkpiel Date: Fri, 15 Dec 2017 16:51:04 -0500 Subject: [PATCH 4/4] doc: not all example code can be run without 1:1 PR-URL: https://github.com/nodejs/node/pull/17702 Reviewed-By: Rich Trott Reviewed-By: Vse Mozhet Byt --- doc/api/synopsis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/synopsis.md b/doc/api/synopsis.md index 7fddd6be3b9f09..ada2437387b7e2 100644 --- a/doc/api/synopsis.md +++ b/doc/api/synopsis.md @@ -38,7 +38,7 @@ $ node example.js Server running at http://127.0.0.1:3000/ ``` -All of the examples in the documentation can be run similarly. +Many of the examples in the documentation can be run similarly. [Command Line Options]: cli.html#cli_command_line_options [web server]: http.html