Skip to content

Commit

Permalink
doc: various documentation formatting fixes
Browse files Browse the repository at this point in the history
* 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
* Fix other broken refs, by addaleax
* 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)

PR-URL: #7637
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Roman Reiss <[email protected]>
  • Loading branch information
ChALkeR committed Jul 14, 2016
1 parent e09c62a commit a58b48b
Show file tree
Hide file tree
Showing 36 changed files with 116 additions and 136 deletions.
12 changes: 6 additions & 6 deletions doc/api/addons.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ top-level of the project describing the build configuration of your module
using a JSON-like format. This file is used by [node-gyp][] -- a tool written
specifically to compile Node.js Addons.

```
```json
{
"targets": [
{
Expand Down Expand Up @@ -222,7 +222,7 @@ templates, etc.

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

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

```
```json
"sources": ["addon.cc", "myexample.cc"]
```

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

```
```sh
$ node-gyp configure build
```

Expand Down Expand Up @@ -621,7 +621,7 @@ void MyObject::PlusOne(const FunctionCallbackInfo<Value>& args) {
To build this example, the `myobject.cc` file must be added to the
`binding.gyp`:
```
```json
{
"targets": [
{
Expand Down Expand Up @@ -813,7 +813,7 @@ void MyObject::PlusOne(const FunctionCallbackInfo<Value>& args) {
Once again, to build this example, the `myobject.cc` file must be added to the
`binding.gyp`:
```
```json
{
"targets": [
{
Expand Down
2 changes: 1 addition & 1 deletion doc/api/buffer.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ significant impact* on performance. Use of the `--zero-fill-buffers` option is
recommended only when absolutely necessary to enforce that newly allocated
`Buffer` instances cannot contain potentially sensitive data.

```
```txt
$ node --zero-fill-buffers
> Buffer.allocUnsafe(5);
<Buffer 00 00 00 00 00>
Expand Down
2 changes: 1 addition & 1 deletion doc/api/cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ if (cluster.isMaster) {

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

```
```txt
$ NODE_DEBUG=cluster node server.js
23521,Master Worker 23524 online
23521,Master Worker 23526 online
Expand Down
6 changes: 3 additions & 3 deletions doc/api/debugger.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ via a simple [TCP-based protocol][] and built-in debugging client. To use it,
start Node.js with the `debug` argument followed by the path to the script to
debug; a prompt will be displayed indicating successful launch of the debugger:

```
```txt
$ node debug myscript.js
< debugger listening on port 5858
connecting... ok
Expand Down Expand Up @@ -38,7 +38,7 @@ console.log('hello');

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

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

```
```txt
$ ./node debug test/fixtures/break-in-module/main.js
< debugger listening on port 5858
connecting to port 5858... ok
Expand Down
1 change: 0 additions & 1 deletion doc/api/dgram.md
Original file line number Diff line number Diff line change
Expand Up @@ -425,7 +425,6 @@ and `udp6` sockets). The bound address and port can be retrieved using
[`EventEmitter`]: events.html
[`Buffer`]: buffer.html
[`'close'`]: #dgram_event_close
[`addMembership()`]: #dgram_socket_addmembership_multicastaddress_multicastinterface
[`close()`]: #dgram_socket_close_callback
[`dgram.createSocket()`]: #dgram_dgram_createsocket_options_callback
[`dgram.Socket#bind()`]: #dgram_socket_bind_options_callback
Expand Down
8 changes: 3 additions & 5 deletions doc/api/dns.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ Alternatively, `options` can be an object containing these properties:

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

```
```js
{
family: 4,
hints: dns.ADDRCONFIG | dns.V4MAPPED,
Expand Down Expand Up @@ -279,7 +279,7 @@ be an object with the following properties:
* `expire`
* `minttl`

```
```js
{
nsname: 'ns.example.com',
hostmaster: 'root.example.com',
Expand All @@ -305,7 +305,7 @@ be an array of objects with the following properties:
* `port`
* `name`

```
```js
{
priority: 10,
weight: 5,
Expand Down Expand Up @@ -437,8 +437,6 @@ uses. For instance, _they do not use the configuration from `/etc/hosts`_.

[DNS error codes]: #dns_error_codes
[`dns.lookup()`]: #dns_dns_lookup_hostname_options_callback
[`dns.resolve()`]: #dns_dns_resolve_hostname_rrtype_callback
[`dns.resolve4()`]: #dns_dns_resolve4_hostname_callback
[`dns.resolveSoa()`]: #dns_dns_resolvesoa_hostname_callback
[`Error`]: errors.html#errors_class_error
[Implementation considerations section]: #dns_implementation_considerations
Expand Down
8 changes: 4 additions & 4 deletions doc/api/documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,26 +37,26 @@ and in the process of being redesigned.

The stability indices are as follows:

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

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

```
```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.
```

```
```txt
Stability: 3 - Locked
Only fixes related to security, performance, or bug fixes will be accepted.
Please do not suggest API changes in this area; they will be refused.
Expand Down
2 changes: 1 addition & 1 deletion doc/api/errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -268,7 +268,7 @@ instantiated.

For example:

```
```txt
Error: Things keep happening!
at /home/gbusey/file.js:525:2
at Frobnicator.refrobulate (/home/gbusey/business-logic.js:424:21)
Expand Down
2 changes: 1 addition & 1 deletion doc/api/fs.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ Most fs functions let you omit the callback argument. If you do, a default
callback is used that rethrows errors. To get a trace to the original call
site, set the `NODE_DEBUG` environment variable:

```
```txt
$ cat script.js
function bad() {
require('fs').readFile('/');
Expand Down
6 changes: 3 additions & 3 deletions doc/api/globals.md
Original file line number Diff line number Diff line change
Expand Up @@ -207,9 +207,9 @@ but rather than loading the module, just return the resolved filename.
[Modules]: modules.html#modules_modules
[native addons]: addons.html
[timers]: timers.html
[`clearImmediate`]: timers.html#timers_clearimmediate_immediateobject
[`clearInterval`]: timers.html#timers_clearinterval_immediateobject
[`clearTimeout`]: timers.html#timers_cleartimeout_timeoutobject
[`clearImmediate`]: timers.html#timers_clearimmediate_immediate
[`clearInterval`]: timers.html#timers_clearinterval_timeout
[`clearTimeout`]: timers.html#timers_cleartimeout_timeout
[`setImmediate`]: timers.html#timers_setimmediate_callback_arg
[`setInterval`]: timers.html#timers_setinterval_callback_delay_arg
[`setTimeout`]: timers.html#timers_settimeout_callback_delay_arg
Expand Down
35 changes: 17 additions & 18 deletions doc/api/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ user is able to stream data.

HTTP message headers are represented by an object like this:

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

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

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

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

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

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

Returns `server`.

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

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

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

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

### server.listening
<!-- YAML
Expand Down Expand Up @@ -1084,7 +1084,7 @@ added: v0.1.17

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

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

```
```txt
GET /status?name=ryan HTTP/1.1\r\n
Accept: text/plain\r\n
\r\n
```

Then `request.url` will be:

```
```js
'/status?name=ryan'
```

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

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

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

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

`http.request()` returns an instance of the [`http.ClientRequest`][]
class. The `ClientRequest` instance is a writable stream. If one needs to
Expand Down Expand Up @@ -1521,7 +1521,6 @@ There are a few special headers that should be noted.
[`socket.setKeepAlive()`]: net.html#net_socket_setkeepalive_enable_initialdelay
[`socket.setNoDelay()`]: net.html#net_socket_setnodelay_nodelay
[`socket.setTimeout()`]: net.html#net_socket_settimeout_timeout_callback
[`stream.setEncoding()`]: stream.html#stream_stream_setencoding_encoding
[`TypeError`]: errors.html#errors_class_typeerror
[`url.parse()`]: url.html#url_url_parse_urlstring_parsequerystring_slashesdenotehost
[constructor options]: #http_new_agent_options
Expand Down
14 changes: 7 additions & 7 deletions doc/api/modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ the `require.resolve()` function.
Putting together all of the above, here is the high-level algorithm
in pseudocode of what require.resolve does:

```
```txt
require(X) from module at path Y
1. If X is a core module,
a. return the core module
Expand Down Expand Up @@ -244,7 +244,7 @@ Consider this situation:

`a.js`:

```
```js
console.log('a starting');
exports.done = false;
const b = require('./b.js');
Expand All @@ -255,7 +255,7 @@ console.log('a done');

`b.js`:

```
```js
console.log('b starting');
exports.done = false;
const a = require('./a.js');
Expand All @@ -266,7 +266,7 @@ console.log('b done');

`main.js`:

```
```js
console.log('main starting');
const a = require('./a.js');
const b = require('./b.js');
Expand All @@ -282,7 +282,7 @@ provided to the `a.js` module.
By the time `main.js` has loaded both modules, they're both finished.
The output of this program would thus be:

```
```txt
$ node main.js
main starting
a starting
Expand Down Expand Up @@ -336,7 +336,7 @@ The first is to create a `package.json` file in the root of the folder,
which specifies a `main` module. An example package.json file might
look like this:

```
```json
{ "name" : "some-library",
"main" : "./lib/some-library.js" }
```
Expand All @@ -351,7 +351,7 @@ Note: If the file specified by the `"main"` entry of `package.json` is missing
and can not be resolved, Node.js will report the entire module as missing with
the default error:

```
```txt
Error: Cannot find module 'some-library'
```

Expand Down
Loading

0 comments on commit a58b48b

Please sign in to comment.