From a58b48bc3bcf43f7090d4cc914606af68fe55815 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A1=D0=BA=D0=BE=D0=B2=D0=BE=D1=80=D0=BE=D0=B4=D0=B0=20?= =?UTF-8?q?=D0=9D=D0=B8=D0=BA=D0=B8=D1=82=D0=B0=20=D0=90=D0=BD=D0=B4=D1=80?= =?UTF-8?q?=D0=B5=D0=B5=D0=B2=D0=B8=D1=87?= Date: Sat, 9 Jul 2016 08:13:09 +0300 Subject: [PATCH] doc: various documentation formatting fixes * Fix markdown code sample in releases.md, it was Reviewed-By: Roman Reiss --- doc/api/addons.md | 12 ++++----- doc/api/buffer.md | 2 +- doc/api/cluster.md | 2 +- doc/api/debugger.md | 6 ++--- doc/api/dgram.md | 1 - doc/api/dns.md | 8 +++--- doc/api/documentation.md | 8 +++--- doc/api/errors.md | 2 +- doc/api/fs.md | 2 +- doc/api/globals.md | 6 ++--- doc/api/http.md | 35 +++++++++++++------------- doc/api/modules.md | 14 +++++------ doc/api/net.md | 4 +-- doc/api/process.md | 25 +++++++++--------- doc/api/repl.md | 4 +-- doc/api/stream.md | 12 +++------ doc/api/synopsis.md | 2 +- doc/api/timers.md | 2 +- doc/api/tls.md | 20 +++++++-------- doc/api/tty.md | 4 +-- doc/api/url.md | 4 +-- doc/api/util.md | 5 ++-- doc/api/v8.md | 2 +- doc/api/vm.md | 3 +-- doc/api/zlib.md | 9 +++---- doc/changelogs/CHANGELOG_V4.md | 6 ++--- doc/changelogs/CHANGELOG_V5.md | 4 +-- doc/changelogs/CHANGELOG_V6.md | 4 +-- doc/ctc-meetings/2016-02-03.md | 2 +- doc/ctc-meetings/2016-06-15.md | 3 +-- doc/guides/building-node-with-ninja.md | 2 +- doc/onboarding-extras.md | 2 +- doc/releases.md | 29 +++++++++++---------- doc/topics/blocking-vs-non-blocking.md | 2 +- doc/topics/domain-postmortem.md | 2 +- doc/tsc-meetings/io.js/2014-12-10.md | 2 +- 36 files changed, 116 insertions(+), 136 deletions(-) diff --git a/doc/api/addons.md b/doc/api/addons.md index 1187eafdc33a63..1333b3b1360e3a 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -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": [ { @@ -222,7 +222,7 @@ templates, etc. Each of these examples using the following `binding.gyp` file: -``` +```json { "targets": [ { @@ -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 ``` @@ -621,7 +621,7 @@ void MyObject::PlusOne(const FunctionCallbackInfo& args) { To build this example, the `myobject.cc` file must be added to the `binding.gyp`: -``` +```json { "targets": [ { @@ -813,7 +813,7 @@ void MyObject::PlusOne(const FunctionCallbackInfo& args) { Once again, to build this example, the `myobject.cc` file must be added to the `binding.gyp`: -``` +```json { "targets": [ { diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 91852a2130310c..b332de1ab212f3 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -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); diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 1c769567c45144..6f0b424e05e083 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -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 diff --git a/doc/api/debugger.md b/doc/api/debugger.md index 6a31212d9c220b..d146292f2d704e 100644 --- a/doc/api/debugger.md +++ b/doc/api/debugger.md @@ -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 @@ -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 @@ -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 diff --git a/doc/api/dgram.md b/doc/api/dgram.md index df479a8e31df60..1a5cce0b91e150 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -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 diff --git a/doc/api/dns.md b/doc/api/dns.md index 3f90d632a85d30..7192be9a861999 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -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, @@ -279,7 +279,7 @@ be an object with the following properties: * `expire` * `minttl` -``` +```js { nsname: 'ns.example.com', hostmaster: 'root.example.com', @@ -305,7 +305,7 @@ be an array of objects with the following properties: * `port` * `name` -``` +```js { priority: 10, weight: 5, @@ -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 diff --git a/doc/api/documentation.md b/doc/api/documentation.md index 61d623fe3e054a..1acb21a8969fa2 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -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. diff --git a/doc/api/errors.md b/doc/api/errors.md index e80dabe609400a..5ede6e6e38ea45 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -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) diff --git a/doc/api/fs.md b/doc/api/fs.md index 022fa0d2cf2732..e2d1597aa7d44c 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -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('/'); diff --git a/doc/api/globals.md b/doc/api/globals.md index 1bd2dffc5fa4df..7db4fbe1aaae00 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -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 diff --git a/doc/api/http.md b/doc/api/http.md index 1a09e96395c7b8..0079ec756670cf 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -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', @@ -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', @@ -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. @@ -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`. @@ -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])