Skip to content

Commit

Permalink
doc: add links and backticks around names
Browse files Browse the repository at this point in the history
* add backticks around names
* add single quotes around event names
* add parenthesis after function names
* add internal links between different sections
* add external links to MDN for some JavaScript references
* sort the link definitions alphabetically

PR-URL: #4054
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
  • Loading branch information
jpersson authored and rvagg committed Dec 5, 2015
1 parent 4b43bf0 commit 3169eed
Show file tree
Hide file tree
Showing 27 changed files with 712 additions and 625 deletions.
21 changes: 13 additions & 8 deletions doc/api/assert.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ comparison operator ( `==` ).
This only considers enumerable properties. It does not test object prototypes,
attached symbols, or non-enumerable properties. This can lead to some
potentially surprising results. For example, this does not throw an
`AssertionError` because the properties on the `Error` object are
`AssertionError` because the properties on the [`Error`][] object are
non-enumerable:

// WARNING: This does not throw an AssertionError!
Expand All @@ -32,11 +32,11 @@ operator ( `===` ).

## assert.doesNotThrow(block[, error][, message])

Expects `block` not to throw an error. See [assert.throws()][] for more details.
Expects `block` not to throw an error. See [`assert.throws()`][] for more details.

If `block` throws an error and if it is of a different type from `error`, the
thrown error will get propagated back to the caller. The following call will
throw the `TypeError`, since we're not matching the error types in the
throw the [`TypeError`][], since we're not matching the error types in the
assertion.

assert.doesNotThrow(
Expand Down Expand Up @@ -72,11 +72,11 @@ argument in callbacks.

## assert.notDeepEqual(actual, expected[, message])

Tests for any deep inequality. Opposite of `assert.deepEqual`.
Tests for any deep inequality. Opposite of [`assert.deepEqual`][].

## assert.notDeepStrictEqual(actual, expected[, message])

Tests for deep inequality. Opposite of `assert.deepStrictEqual`.
Tests for deep inequality. Opposite of [`assert.deepStrictEqual`][].

## assert.notEqual(actual, expected[, message])

Expand All @@ -94,7 +94,7 @@ Tests strict equality as determined by the strict equality operator ( `===` ).

## assert.throws(block[, error][, message])

Expects `block` to throw an error. `error` can be a constructor, `RegExp`, or
Expects `block` to throw an error. `error` can be a constructor, [`RegExp`][], or
validation function.

Validate instanceof using constructor:
Expand All @@ -106,7 +106,7 @@ Validate instanceof using constructor:
Error
);

Validate error message using RegExp:
Validate error message using [`RegExp`][]:

assert.throws(
function() {
Expand All @@ -129,4 +129,9 @@ Custom error validation:
"unexpected error"
);

[assert.throws()]: #assert_assert_throws_block_error_message
[`assert.deepEqual`]: #assert_assert_deepequal_actual_expected_message
[`assert.deepStrictEqual`]: #assert_assert_deepstrictequal_actual_expected_message
[`assert.throws()`]: #assert_assert_throws_block_error_message
[`Error`]: errors.html#errors_class_error
[`RegExp`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
[`TypeError`]: errors.html#errors_class_typeerror
25 changes: 15 additions & 10 deletions doc/api/buffer.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ instead of cloning it.

While more efficient, it introduces subtle incompatibilities with the typed
arrays specification. `ArrayBuffer#slice()` makes a copy of the slice while
`Buffer#slice()` creates a view.
[`Buffer#slice()`][] creates a view.

## Class: Buffer

Expand All @@ -76,11 +76,11 @@ Copies the passed `buffer` data onto a new `Buffer` instance.
Allocates a new buffer of `size` bytes. `size` must be less than
1,073,741,824 bytes (1 GB) on 32 bits architectures or
2,147,483,648 bytes (2 GB) on 64 bits architectures,
otherwise a `RangeError` is thrown.
otherwise a [`RangeError`][] is thrown.

Unlike `ArrayBuffers`, the underlying memory for buffers is not initialized. So
the contents of a newly created `Buffer` are unknown and could contain
sensitive data. Use `buf.fill(0)` to initialize a buffer to zeroes.
sensitive data. Use [`buf.fill(0)`][] to initialize a buffer to zeroes.

### new Buffer(str[, encoding])

Expand All @@ -97,7 +97,7 @@ Allocates a new buffer containing the given `str`.
* Return: Number

Gives the actual byte length of a string. `encoding` defaults to `'utf8'`.
This is not the same as `String.prototype.length` since that returns the
This is not the same as [`String.prototype.length`][] since that returns the
number of *characters* in a string.

Example:
Expand Down Expand Up @@ -286,9 +286,9 @@ buffer.
* `byteOffset` Number, Optional, Default: 0
* Return: Number

Operates similar to [Array#indexOf()][]. Accepts a String, Buffer or Number.
Operates similar to [`Array#indexOf()`][]. Accepts a String, Buffer or Number.
Strings are interpreted as UTF8. Buffers will use the entire buffer. So in order
to compare a partial Buffer use `Buffer#slice()`. Numbers can range from 0 to
to compare a partial Buffer use [`Buffer#slice()`][]. Numbers can range from 0 to
255.

### buf.length
Expand All @@ -311,7 +311,7 @@ buffer object. It does not change when the contents of the buffer are changed.
While the `length` property is not immutable, changing the value of `length`
can result in undefined and inconsistent behavior. Applications that wish to
modify the length of a buffer should therefore treat `length` as read-only and
use `buf.slice` to create a new buffer.
use [`buf.slice`][] to create a new buffer.

buf = new Buffer(10);
buf.write("abcdefghj", 0, "ascii");
Expand Down Expand Up @@ -882,7 +882,7 @@ to `false`.
* Number, Default: 50

How many bytes will be returned when `buffer.inspect()` is called. This can
be overridden by user modules. See [util.inspect()][] for more details on
be overridden by user modules. See [`util.inspect()`][] for more details on
`buffer.inspect()` behavior.

Note that this is a property on the buffer module returned by
Expand Down Expand Up @@ -932,6 +932,11 @@ un-pooled Buffer instance using SlowBuffer and copy out the relevant bits.
Though this should be used sparingly and only be a last resort *after* a developer
has actively observed undue memory retention in their applications.

[`Array#indexOf()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf
[`buf.fill(0)`]: #buffer_buf_fill_value_offset_end
[`buf.slice`]: #buffer_buf_slice_start_end
[`buf1.compare(buf2)`]: #buffer_buf_compare_otherbuffer
[Array#indexOf()]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf
[util.inspect()]: util.html#util_util_inspect_object_options
[`Buffer#slice()`]: #buffer_buf_slice_start_end
[`RangeError`]: errors.html#errors_class_rangeerror
[`String.prototype.length`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length
[`util.inspect()`]: util.html#util_util_inspect_object_options
68 changes: 36 additions & 32 deletions doc/api/child_process.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,15 @@ convenient.

## Class: ChildProcess

`ChildProcess` is an [EventEmitter][].
`ChildProcess` is an [`EventEmitter`][].

Child processes always have three streams associated with them. `child.stdin`,
`child.stdout`, and `child.stderr`. These may be shared with the stdio
streams of the parent process, or they may be separate stream objects
which can be piped to and from.

The ChildProcess class is not intended to be used directly. Use the
`spawn()`, `exec()`, `execFile()`, or `fork()` methods to create a Child
[`spawn()`][], [`exec()`][], [`execFile()`][], or [`fork()`][] methods to create a Child
Process instance.

### Event: 'close'
Expand All @@ -37,7 +37,7 @@ Process instance.
was killed by the parent.

This event is emitted when the stdio streams of a child process have all
terminated. This is distinct from 'exit', since multiple processes
terminated. This is distinct from `'exit'`, since multiple processes
might share the same stdio streams.

### Event: 'disconnect'
Expand All @@ -56,7 +56,7 @@ Emitted when:
2. The process could not be killed, or
3. Sending a message to the child process failed for whatever reason.

Note that the `exit`-event may or may not fire after an error has occurred. If
Note that the `'exit'` event may or may not fire after an error has occurred. If
you are listening on both events to fire a function, remember to guard against
calling your function twice.

Expand All @@ -75,20 +75,20 @@ of the signal, otherwise `null`.

Note that the child process stdio streams might still be open.

Also, note that Node.js establishes signal handlers for `'SIGINT'` and
`'SIGTERM`', so it will not terminate due to receipt of those signals,
Also, note that Node.js establishes signal handlers for `SIGINT` and
`SIGTERM`, so it will not terminate due to receipt of those signals,
it will exit.

See `waitpid(2)`.

### Event: 'message'

* `message` {Object} a parsed JSON object or primitive value.
* `sendHandle` {Handle object} a [net.Socket][] or [net.Server][] object, or
* `sendHandle` {Handle object} a [`net.Socket`][] or [`net.Server`][] object, or
undefined.

Messages sent by `.send(message, [sendHandle])` are obtained using the
`message` event.
`'message'` event.

### child.connected

Expand All @@ -103,11 +103,11 @@ gracefully once there are no other connections keeping it alive. After calling
this method the `.connected` flag will be set to `false` in both the parent and
child, and it is no longer possible to send messages.

The 'disconnect' event will be emitted when there are no messages in the process
The `'disconnect'` event will be emitted when there are no messages in the process
of being received, most likely immediately.

Note that you can also call `process.disconnect()` in the child process when the
child process has any open IPC channels with the parent (i.e `fork()`).
child process has any open IPC channels with the parent (i.e [`fork()`][]).

### child.kill([signal])

Expand Down Expand Up @@ -188,17 +188,17 @@ will emit objects each time it receives a message on its channel.

There is a special case when sending a `{cmd: 'NODE_foo'}` message. All messages
containing a `NODE_` prefix in its `cmd` property will not be emitted in
the `message` event, since they are internal messages used by Node.js core.
Messages containing the prefix are emitted in the `internalMessage` event.
the `'message'` event, since they are internal messages used by Node.js core.
Messages containing the prefix are emitted in the `'internalMessage'` event.
Avoid using this feature; it is subject to change without notice.

The `sendHandle` option to `child.send()` is for sending a TCP server or
socket object to another process. The child will receive the object as its
second argument to the `message` event.
second argument to the `'message'` event.

The `callback` option is a function that is invoked after the message is
sent but before the target may have received it. It is called with a single
argument: `null` on success, or an `Error` object on failure.
argument: `null` on success, or an [`Error`][] object on failure.

`child.send()` emits an `'error'` event if no callback was given and the message
cannot be sent, for example because the child process has already exited.
Expand Down Expand Up @@ -237,7 +237,7 @@ Note that the server is now shared between the parent and child, this means
that some connections will be handled by the parent and some by the child.

For `dgram` servers the workflow is exactly the same. Here you listen on
a `message` event instead of `connection` and use `server.bind` instead of
a `'message'` event instead of `'connection'` and use `server.bind` instead of
`server.listen`. (Currently only supported on UNIX platforms.)

#### Example: sending socket object
Expand Down Expand Up @@ -308,7 +308,7 @@ to the same object, or null.
* {Array}

A sparse array of pipes to the child process, corresponding with positions in
the [stdio][] option to [spawn][] that have been set to `'pipe'`.
the [`stdio`][] option to [`spawn()`][] that have been set to `'pipe'`.
Note that streams 0-2 are also available as ChildProcess.stdin,
ChildProcess.stdout, and ChildProcess.stderr, respectively.

Expand Down Expand Up @@ -392,7 +392,7 @@ Runs a command in a shell and buffers the output.
});

The callback gets the arguments `(error, stdout, stderr)`. On success, `error`
will be `null`. On error, `error` will be an instance of `Error` and `error.code`
will be `null`. On error, `error` will be an instance of [`Error`][] and `error.code`
will be the exit code of the child process, and `error.signal` will be set to the
signal that terminated the process.

Expand Down Expand Up @@ -452,7 +452,7 @@ leaner than [`child_process.exec()`][]. It has the same options.
(Default: `process.execArgv`)
* `silent` {Boolean} If true, stdin, stdout, and stderr of the child will be
piped to the parent, otherwise they will be inherited from the parent, see
the "pipe" and "inherit" options for `spawn()`'s `stdio` for more details
the `'pipe'` and `'inherit'` options for [`spawn()`][]'s [`stdio`][] for more details
(default is false)
* `uid` {Number} Sets the user identity of the process. (See setuid(2).)
* `gid` {Number} Sets the group identity of the process. (See setgid(2).)
Expand All @@ -473,7 +473,7 @@ done with care and by default will talk over the fd represented an
environmental variable `NODE_CHANNEL_FD` on the child process. The input and
output on this fd is expected to be line delimited JSON objects.

*Note: Unlike the `fork()` POSIX system call, `child_process.fork()` does not clone the
*Note: Unlike the `fork()` POSIX system call, [`child_process.fork()`][] does not clone the
current process.*

### child_process.spawn(command[, args][, options])
Expand Down Expand Up @@ -614,7 +614,7 @@ As a shorthand, the `stdio` argument may be one of the following strings:
* `'ignore'` - `['ignore', 'ignore', 'ignore']`
* `'inherit'` - `[process.stdin, process.stdout, process.stderr]` or `[0,1,2]`

Otherwise, the 'stdio' option to `child_process.spawn()` is an array where each
Otherwise, the `'stdio'` option to [`child_process.spawn()`][] is an array where each
index corresponds to a fd in the child. The value is one of the following:

1. `'pipe'` - Create a pipe between the child process and the parent process.
Expand Down Expand Up @@ -698,7 +698,7 @@ the `SIGTERM` signal and doesn't exit, your process will wait until the child
process has exited.

If the process times out, or has a non-zero exit code, this method ***will***
throw. The `Error` object will contain the entire result from
throw. The [`Error`][] object will contain the entire result from
[`child_process.spawnSync()`][]

### child_process.execSync(command[, options])
Expand Down Expand Up @@ -732,7 +732,7 @@ the `SIGTERM` signal and doesn't exit, your process will wait until the child
process has exited.

If the process times out, or has a non-zero exit code, this method ***will***
throw. The `Error` object will contain the entire result from
throw. The [`Error`][] object will contain the entire result from
[`child_process.spawnSync()`][]

### child_process.spawnSync(command[, args][, options])
Expand Down Expand Up @@ -767,16 +767,20 @@ until the process has completely exited. That is to say, if the process handles
the `SIGTERM` signal and doesn't exit, your process will wait until the child
process has exited.

[below]: #child_process_asynchronous_process_creation
[synchronous counterparts]: #child_process_synchronous_process_creation
[EventEmitter]: events.html#events_class_events_eventemitter
[`ChildProcess#kill()`]: #child_process_child_kill_signal
[`ChildProcess#send()`]: #child_process_child_send_message_sendhandle_callback
[net.Server]: net.html#net_class_net_server
[net.Socket]: net.html#net_class_net_socket
[`child_process.fork()`]: #child_process_child_process_fork_modulepath_args_options
[stdio]: #child_process_options_stdio
[spawn]: #child_process_child_process_spawn_command_args_options
[`child_process.exec()`]: #child_process_child_process_exec_command_options_callback
[`child_process.fork()`]: #child_process_child_process_fork_modulepath_args_options
[`child_process.spawn()`]: #child_process_child_process_spawn_command_args_options
[`child_process.spawnSync()`]: #child_process_child_process_spawnsync_command_args_options
[`ChildProcess#kill()`]: #child_process_child_kill_signal
[`ChildProcess#send()`]: #child_process_child_send_message_sendhandle_callback
[`Error`]: errors.html#errors_class_error
[`EventEmitter`]: events.html#events_class_events_eventemitter
[`exec()`]: #child_process_child_process_exec_command_options_callback
[`execFile()`]: #child_process_child_process_execfile_file_args_options_callback
[`fork()`]: #child_process_child_process_fork_modulepath_args_options
[`net.Server`]: net.html#net_class_net_server
[`net.Socket`]: net.html#net_class_net_socket
[`spawn()`]: #child_process_child_process_spawn_command_args_options
[`stdio`]: #child_process_options_stdio
[below]: #child_process_asynchronous_process_creation
[synchronous counterparts]: #child_process_synchronous_process_creation
Loading

0 comments on commit 3169eed

Please sign in to comment.