Skip to content

Commit 5e90edc

Browse files
committed
doc: various documentation formatting fixes
* Fix markdown code sample in releases.md, it was <a id="x.y.x></a>" * Fix some markdown errors, e.g. in changelogs * Fix broken defs links, e.g. in domain-postmortem.md * Add links to some defs that were present but not linked to * Remove dead defs * Move defs to the bottom (one file affected) * Add language indicators to all code blocks, using `txt` when no specific language could be chosen * Some minor formatting changes (spaces, ident, headings)
1 parent 990c968 commit 5e90edc

34 files changed

Lines changed: 109 additions & 128 deletions

doc/api/addons.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ top-level of the project describing the build configuration of your module
102102
using a JSON-like format. This file is used by [node-gyp][] -- a tool written
103103
specifically to compile Node.js Addons.
104104

105-
```
105+
```json
106106
{
107107
"targets": [
108108
{
@@ -222,7 +222,7 @@ templates, etc.
222222

223223
Each of these examples using the following `binding.gyp` file:
224224

225-
```
225+
```json
226226
{
227227
"targets": [
228228
{
@@ -236,14 +236,14 @@ Each of these examples using the following `binding.gyp` file:
236236
In cases where there is more than one `.cc` file, simply add the additional
237237
filename to the `sources` array. For example:
238238

239-
```
239+
```json
240240
"sources": ["addon.cc", "myexample.cc"]
241241
```
242242

243243
Once the `binding.gyp` file is ready, the example Addons can be configured and
244244
built using `node-gyp`:
245245

246-
```
246+
```sh
247247
$ node-gyp configure build
248248
```
249249

@@ -621,7 +621,7 @@ void MyObject::PlusOne(const FunctionCallbackInfo<Value>& args) {
621621
To build this example, the `myobject.cc` file must be added to the
622622
`binding.gyp`:
623623
624-
```
624+
```json
625625
{
626626
"targets": [
627627
{
@@ -813,7 +813,7 @@ void MyObject::PlusOne(const FunctionCallbackInfo<Value>& args) {
813813
Once again, to build this example, the `myobject.cc` file must be added to the
814814
`binding.gyp`:
815815
816-
```
816+
```json
817817
{
818818
"targets": [
819819
{

doc/api/buffer.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ significant impact* on performance. Use of the `--zero-fill-buffers` option is
114114
recommended only when absolutely necessary to enforce that newly allocated
115115
`Buffer` instances cannot contain potentially sensitive data.
116116

117-
```
117+
```txt
118118
$ node --zero-fill-buffers
119119
> Buffer.allocUnsafe(5);
120120
<Buffer 00 00 00 00 00>

doc/api/cluster.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ if (cluster.isMaster) {
3535

3636
Running Node.js will now share port 8000 between the workers:
3737

38-
```
38+
```txt
3939
$ NODE_DEBUG=cluster node server.js
4040
23521,Master Worker 23524 online
4141
23521,Master Worker 23526 online

doc/api/debugger.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ via a simple [TCP-based protocol][] and built-in debugging client. To use it,
99
start Node.js with the `debug` argument followed by the path to the script to
1010
debug; a prompt will be displayed indicating successful launch of the debugger:
1111

12-
```
12+
```txt
1313
$ node debug myscript.js
1414
< debugger listening on port 5858
1515
connecting... ok
@@ -38,7 +38,7 @@ console.log('hello');
3838

3939
Once the debugger is run, a breakpoint will occur at line 4:
4040

41-
```
41+
```txt
4242
$ node debug myscript.js
4343
< debugger listening on port 5858
4444
connecting... ok
@@ -119,7 +119,7 @@ on line 1
119119
It is also possible to set a breakpoint in a file (module) that
120120
isn't loaded yet:
121121

122-
```
122+
```txt
123123
$ ./node debug test/fixtures/break-in-module/main.js
124124
< debugger listening on port 5858
125125
connecting to port 5858... ok

doc/api/dgram.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -424,7 +424,6 @@ and `udp6` sockets). The bound address and port can be retrieved using
424424
[`EventEmitter`]: events.html
425425
[`Buffer`]: buffer.html
426426
[`'close'`]: #dgram_event_close
427-
[`addMembership()`]: #dgram_socket_addmembership_multicastaddress_multicastinterface
428427
[`close()`]: #dgram_socket_close_callback
429428
[`dgram.createSocket()`]: #dgram_dgram_createsocket_options_callback
430429
[`dgram.Socket#bind()`]: #dgram_socket_bind_options_callback

doc/api/dns.md

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ Alternatively, `options` can be an object containing these properties:
8686

8787
All properties are optional. An example usage of options is shown below.
8888

89-
```
89+
```js
9090
{
9191
family: 4,
9292
hints: dns.ADDRCONFIG | dns.V4MAPPED,
@@ -277,7 +277,7 @@ be an object with the following properties:
277277
* `expire`
278278
* `minttl`
279279

280-
```
280+
```js
281281
{
282282
nsname: 'ns.example.com',
283283
hostmaster: 'root.example.com',
@@ -303,7 +303,7 @@ be an array of objects with the following properties:
303303
* `port`
304304
* `name`
305305

306-
```
306+
```js
307307
{
308308
priority: 10,
309309
weight: 5,
@@ -435,8 +435,6 @@ uses. For instance, _they do not use the configuration from `/etc/hosts`_.
435435

436436
[DNS error codes]: #dns_error_codes
437437
[`dns.lookup()`]: #dns_dns_lookup_hostname_options_callback
438-
[`dns.resolve()`]: #dns_dns_resolve_hostname_rrtype_callback
439-
[`dns.resolve4()`]: #dns_dns_resolve4_hostname_callback
440438
[`Error`]: errors.html#errors_class_error
441439
[Implementation considerations section]: #dns_implementation_considerations
442440
[supported `getaddrinfo` flags]: #dns_supported_getaddrinfo_flags

doc/api/documentation.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,26 +37,26 @@ and in the process of being redesigned.
3737

3838
The stability indices are as follows:
3939

40-
```
40+
```txt
4141
Stability: 0 - Deprecated
4242
This feature is known to be problematic, and changes are
4343
planned. Do not rely on it. Use of the feature may cause warnings. Backwards
4444
compatibility should not be expected.
4545
```
4646

47-
```
47+
```txt
4848
Stability: 1 - Experimental
4949
This feature is subject to change, and is gated by a command line flag.
5050
It may change or be removed in future versions.
5151
```
5252

53-
```
53+
```txt
5454
Stability: 2 - Stable
5555
The API has proven satisfactory. Compatibility with the npm ecosystem
5656
is a high priority, and will not be broken unless absolutely necessary.
5757
```
5858

59-
```
59+
```txt
6060
Stability: 3 - Locked
6161
Only fixes related to security, performance, or bug fixes will be accepted.
6262
Please do not suggest API changes in this area; they will be refused.

doc/api/errors.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -268,7 +268,7 @@ instantiated.
268268

269269
For example:
270270

271-
```
271+
```txt
272272
Error: Things keep happening!
273273
at /home/gbusey/file.js:525:2
274274
at Frobnicator.refrobulate (/home/gbusey/business-logic.js:424:21)

doc/api/fs.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ Most fs functions let you omit the callback argument. If you do, a default
7474
callback is used that rethrows errors. To get a trace to the original call
7575
site, set the `NODE_DEBUG` environment variable:
7676

77-
```
77+
```txt
7878
$ cat script.js
7979
function bad() {
8080
require('fs').readFile('/');

doc/api/http.md

Lines changed: 17 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ user is able to stream data.
1212

1313
HTTP message headers are represented by an object like this:
1414

15-
```
15+
```js
1616
{ 'content-length': '123',
1717
'content-type': 'text/plain',
1818
'connection': 'keep-alive',
@@ -34,7 +34,7 @@ property, which is an array of `[key, value, key2, value2, ...]`. For
3434
example, the previous message header object might have a `rawHeaders`
3535
list like the following:
3636

37-
```
37+
```js
3838
[ 'ConTent-Length', '123456',
3939
'content-LENGTH', '123',
4040
'content-type', 'text/plain',
@@ -222,16 +222,16 @@ header is still mutable using the `setHeader(name, value)`, `getHeader(name)`,
222222
`removeHeader(name)` API. The actual header will be sent along with the first
223223
data chunk or when closing the connection.
224224

225-
To get the response, add a listener for `'response'` to the request object.
226-
`'response'` will be emitted from the request object when the response
227-
headers have been received. The `'response'` event is executed with one
225+
To get the response, add a listener for [`'response'`][] to the request object.
226+
[`'response'`][] will be emitted from the request object when the response
227+
headers have been received. The [`'response'`][] event is executed with one
228228
argument which is an instance of [`http.IncomingMessage`][].
229229

230-
During the `'response'` event, one can add listeners to the
230+
During the [`'response'`][] event, one can add listeners to the
231231
response object; particularly to listen for the `'data'` event.
232232

233-
If no `'response'` handler is added, then the response will be
234-
entirely discarded. However, if you add a `'response'` event handler,
233+
If no [`'response'`][] handler is added, then the response will be
234+
entirely discarded. However, if you add a [`'response'`][] event handler,
235235
then you **must** consume the data from the response object, either by
236236
calling `response.read()` whenever there is a `'readable'` event, or
237237
by adding a `'data'` handler, or by calling the `.resume()` method.
@@ -677,7 +677,7 @@ already been bound to a port or domain socket.
677677
Listening on a file descriptor is not supported on Windows.
678678

679679
This function is asynchronous. `callback` will be added as a listener for the
680-
`'listening'` event. See also [`net.Server.listen()`][].
680+
[`'listening'`][] event. See also [`net.Server.listen()`][].
681681

682682
Returns `server`.
683683

@@ -689,7 +689,7 @@ added: v0.1.90
689689
Start a UNIX socket server listening for connections on the given `path`.
690690

691691
This function is asynchronous. `callback` will be added as a listener for the
692-
`'listening'` event. See also [`net.Server.listen(path)`][].
692+
[`'listening'`][] event. See also [`net.Server.listen(path)`][].
693693

694694
### server.listen(port[, hostname][, backlog][, callback])
695695
<!-- YAML
@@ -709,7 +709,7 @@ The actual length will be determined by your OS through sysctl settings such as
709709
parameter is 511 (not 512).
710710

711711
This function is asynchronous. `callback` will be added as a listener for the
712-
`'listening'` event. See also [`net.Server.listen(port)`][].
712+
[`'listening'`][] event. See also [`net.Server.listen(port)`][].
713713

714714
### server.listening
715715
<!-- YAML
@@ -1084,7 +1084,7 @@ added: v0.1.17
10841084

10851085
An `IncomingMessage` object is created by [`http.Server`][] or
10861086
[`http.ClientRequest`][] and passed as the first argument to the `'request'`
1087-
and `'response'` event respectively. It may be used to access response status,
1087+
and [`'response'`][] event respectively. It may be used to access response status,
10881088
headers and data.
10891089

10901090
It implements the [Readable Stream][] interface, as well as the
@@ -1264,22 +1264,22 @@ added: v0.1.90
12641264
Request URL string. This contains only the URL that is
12651265
present in the actual HTTP request. If the request is:
12661266

1267-
```
1267+
```txt
12681268
GET /status?name=ryan HTTP/1.1\r\n
12691269
Accept: text/plain\r\n
12701270
\r\n
12711271
```
12721272

12731273
Then `request.url` will be:
12741274

1275-
```
1275+
```js
12761276
'/status?name=ryan'
12771277
```
12781278

12791279
If you would like to parse the URL into its parts, you can use
12801280
`require('url').parse(request.url)`. Example:
12811281

1282-
```
1282+
```txt
12831283
$ node
12841284
> require('url').parse('/status?name=ryan')
12851285
{
@@ -1294,7 +1294,7 @@ If you would like to extract the parameters from the query string,
12941294
you can use the `require('querystring').parse` function, or pass
12951295
`true` as the second argument to `require('url').parse`. Example:
12961296

1297-
```
1297+
```txt
12981298
$ node
12991299
> require('url').parse('/status?name=ryan', true)
13001300
{
@@ -1419,7 +1419,7 @@ Options:
14191419
function. See [`agent.createConnection()`][] for more details.
14201420

14211421
The optional `callback` parameter will be added as a one time listener for
1422-
the `'response'` event.
1422+
the [`'response'`][] event.
14231423

14241424
`http.request()` returns an instance of the [`http.ClientRequest`][]
14251425
class. The `ClientRequest` instance is a writable stream. If one needs to
@@ -1521,7 +1521,6 @@ There are a few special headers that should be noted.
15211521
[`socket.setKeepAlive()`]: net.html#net_socket_setkeepalive_enable_initialdelay
15221522
[`socket.setNoDelay()`]: net.html#net_socket_setnodelay_nodelay
15231523
[`socket.setTimeout()`]: net.html#net_socket_settimeout_timeout_callback
1524-
[`stream.setEncoding()`]: stream.html#stream_stream_setencoding_encoding
15251524
[`TypeError`]: errors.html#errors_class_typeerror
15261525
[`url.parse()`]: url.html#url_url_parse_urlstring_parsequerystring_slashesdenotehost
15271526
[constructor options]: #http_new_agent_options

0 commit comments

Comments
 (0)