8000 doc: improve documentation.md · nodejs/node@6abd459 · GitHub
[go: up one dir, main page]
Skip to content

Commit 6abd459

Browse files
Fishrock123MylesBorins
Fishrock123
authored and
MylesBorins
committed
doc: improve documentation.md
Reworded some parts, inter-doc links. PR-URL: #17702 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
1 parent bdb535c commit 6abd459

File tree

1 file changed

+30
-27
lines changed

1 file changed

+30
-27
lines changed

‎doc/api/documentation.md‎

Lines changed: 30 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -11,20 +11,16 @@ Where appropriate, property types, method arguments, and the arguments
1111
provided to event handlers are detailed in a list underneath the topic
1212
heading.
1313

14-
Every `.html` document has a corresponding `.json` document presenting
15-
the same information in a structured manner. This feature is
16-
experimental, and added for the benefit of IDEs and other utilities that
17-
wish to do programmatic things with the documentation.
18-
19-
Every `.html` and `.json` file is generated based on the corresponding
20-
`.md` file in the `doc/api/` folder in Node.js's source tree. The
21-
documentation is generated using the `tools/doc/generate.js` program.
22-
The HTML template is located at `doc/template.html`.
23-
14+
## Contributing
2415

2516
If you find an error in this documentation, please [submit an issue][]
2617
or see [the contributing guide][] for directions on how to submit a patch.
2718

19+
Every file is generated based on the corresponding `.md` file in the
20+
`doc/api/` folder in Node.js's source tree. The documentation is generated
21+
using the `tools/doc/generate.js` program. An HTML template is located at
22+
`doc/template.html`.
23+
2824
## Stability Index
2925

3026
<!--type=misc-->
@@ -53,40 +49,43 @@ is not recommended in production environments. Experimental features are not
5349
subject to the Node.js Semantic Versioning model.
5450
```
5551

56-
*Note*: Caution must be used when making use of `Experimental` features,
57-
particularly within modules that may be used as dependencies (or dependencies
58-
of dependencies) within a Node.js application. End users may not be aware that
59-
experimental features are being used, and therefore may experience unexpected
60-
failures or behavioral changes when changes occur. To help avoid such surprises,
61-
`Experimental` features may require a command-line flag to explicitly enable
62-
them, or may cause a process warning to be emitted. By default, such warnings
63-
are printed to `stderr` and may be handled by attaching a listener to the
64-
`process.on('warning')` event.
65-
6652
```txt
6753
Stability: 2 - Stable
6854
The API has proven satisfactory. Compatibility with the npm ecosystem
6955
is a high priority, and will not be broken unless absolutely necessary.
7056
```
7157

58+
*Note*: Caution must be used when making use of `Experimental` features,
59+
particularly within modules that may be used as dependencies (or dependencies
60+
of dependencies) within a Node.js application. End users may not be aware that
61+
experimental features are being used, and therefore may experience unexpected
62+
failures or behavior changes when API modifications occur. To help avoid such
63+
surprises, `Experimental` features may require a command-line flag to
64+
explicitly enable them, or may cause a process warning to be emitted.
65+
By default, such warnings are printed to [`stderr`][] and may be handled by
66+
attaching a listener to the [`process.on('warning')`][] event.
67+
7268
## JSON Output
69+
<!-- YAML
70+
added: v0.6.12
71+
-->
7372

7473
> Stability: 1 - Experimental
7574
76-
Every HTML file in the markdown has a corresponding JSON file with the
77-
same data.
78-
79-
This feature was added in Node.js v0.6.12. It is experimental.
75+
Every `.html` document has a corresponding `.json` document presenting
76+
the same information in a structured manner. This feature is
77+
experimental, and added for the benefit of IDEs and other utilities that
78+
wish to do programmatic things with the documentation.
8079

8180
## Syscalls and man pages
8281

8382
System calls like open(2) and read(2) define the interface between user programs
8483
and the underlying operating system. Node functions which simply wrap a syscall,
85-
like `fs.open()`, will document that. The docs link to the corresponding man
84+
like [`fs.open()`][], will document that. The docs link to the corresponding man
8685
pages (short for manual pages) which describe how the syscalls work.
8786

88-
**Note:** some syscalls, like lchown(2), are BSD-specific. That means, for
89-
example, that `fs.lchown()` only works on macOS and other BSD-derived systems,
87+
Some syscalls, like lchown(2), are BSD-specific. That means, for
88+
example, that [`fs.lchown()`][] only works on macOS and other BSD-derived systems,
9089
and is not available on Linux.
9190

9291
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).
9695

9796
[submit an issue]: https://github.com/nodejs/node/issues/new
9897
[the contributing guide]: https://github.com/nodejs/node/blob/master/CONTRIBUTING.md
98+
[`stderr`]: process.html#process_process_stderr
99+
[`process.on('warning')`]: process.html#process_event_warning
100+
[`fs.open()`]: fs.html#fs_fs_open_path_flags_mode_callback
101+
[`fs.lchown()`]: fs.html#fs_fs_lchown_path_uid_gid_callback

0 commit comments

Comments
 (0)
0