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
* 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 <anna@addaleax.net>
Reviewed-By: Roman Reiss <me@silverwind.io>

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<Value>& 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<Value>& args) {
 Once again, to build this example, the `myobject.cc` file must be added to the
 `binding.gyp`:
 
-```
+```json
 {
   "targets": [
     {

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);
 <Buffer 00 00 00 00 00>

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

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

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

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

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.

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)

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('/');

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

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])
 <!-- YAML
@@ -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
@@ -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
@@ -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')
 {
@@ -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)
 {
@@ -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
@@ -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

doc/api/modules.md

@@ -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
@@ -244,7 +244,7 @@ Consider this situation:
 
 `a.js`:
 
-```
+```js
 console.log('a starting');
 exports.done = false;
 const b = require('./b.js');
@@ -255,7 +255,7 @@ console.log('a done');
 
 `b.js`:
 
-```
+```js
 console.log('b starting');
 exports.done = false;
 const a = require('./a.js');
@@ -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');
@@ -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
@@ -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" }
 ```
@@ -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'
 ```