From f6908638cceda878db01429cbe00186ddc854622 Mon Sep 17 00:00:00 2001
From: Roman Reiss <me@silverwind.io>
Date: Fri, 9 Dec 2016 20:17:53 +0100
Subject: [PATCH 1/6] doc: clarify dns.resolve API

---
 doc/api/dns.md | 47 ++++++++++++++++++++++++++---------------------
 1 file changed, 26 insertions(+), 21 deletions(-)

diff --git a/doc/api/dns.md b/doc/api/dns.md
index 329ff0c3ae028a..8e879f0a4f3c80 100644
--- a/doc/api/dns.md
+++ b/doc/api/dns.md
@@ -174,30 +174,26 @@ added: v0.1.27
   - `addresses` {string[] | Object[] | string[][] | Object}
 
 Uses the DNS protocol to resolve a hostname (e.g. `'nodejs.org'`) into an
-array of the record types specified by `rrtype`.
-
-Valid values for `rrtype` are:
-
- * `'A'` - IPV4 addresses, default
- * `'AAAA'` - IPV6 addresses
- * `'MX'` - mail exchange records
- * `'TXT'` - text records
- * `'SRV'` - SRV records
- * `'PTR'` - PTR records
- * `'NS'` - name server records
- * `'CNAME'` - canonical name records
- * `'SOA'` - start of authority record
- * `'NAPTR'` - name authority pointer record
+array of the resource records, specified by `rrtype` (resource record type):
+
+| `rrtype`  | Return array contains          | Result type | Shorthand method         |
+|-----------|--------------------------------|-------------|--------------------------|
+| `'A'`     | IPv4 addresses (default)       | {String}    | [`dns.resolve4()`][]     |
+| `'AAAA'`  | IPv6 addresses                 | {String}    | [`dns.resolve6()`][]     |
+| `'CNAME'` | canonical name records         | {String}    | [`dns.resolveCname()`][] |
+| `'MX'`    | mail exchange records          | {Object}    | [`dns.resolveMx()`][]    |
+| `'NAPTR'` | name authority pointer records | {Object}    | [`dns.resolveNaptr()`][] |
+| `'NS'`    | name server records            | {String}    | [`dns.resolveNs()`][]    |
+| `'PTR'`   | pointer records                | {String}    | [`dns.resolvePtr()`][]   |
+| `'SOA'`   | start of authority records     | {Object}    | [`dns.resolveSoa()`][]   |
+| `'SRV'`   | service records                | {Object}    | [`dns.resolveSrv()`][]   |
+| `'TXT'`   | text records                   | {String}    | [`dns.resolveTxt()`][]   |
 
 The `callback` function has arguments `(err, addresses)`. When successful,
-`addresses` will be an array, except when resolving an SOA record which returns
-an object structured in the same manner as one returned by the
-[`dns.resolveSoa()`][] method. The type of each item in `addresses` is
-determined by the record type, and described in the documentation for the
-corresponding lookup methods.
+`addresses` will be an array of results.
 
-On error, `err` is an [`Error`][] object, where `err.code` is
-one of the error codes listed [here](#dns_error_codes).
+On error, `err` is an [`Error`][] object, where `err.code` is one of the
+[DNS error codes](#dns_error_codes).
 
 ## dns.resolve4(hostname[, options], callback)
 <!-- YAML
@@ -516,7 +512,16 @@ 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.resolve4()`]: #dns_dns_resolve4_hostname_options_callback
+[`dns.resolve6()`]: #dns_dns_resolve6_hostname_options_callback
+[`dns.resolveCname()`]: #dns_dns_resolvecname_hostname_callback
+[`dns.resolveMx()`]: #dns_dns_resolvemx_hostname_callback
+[`dns.resolveNaptr()`]: #dns_dns_resolvenaptr_hostname_callback
+[`dns.resolveNs()`]: #dns_dns_resolvens_hostname_callback
+[`dns.resolvePtr()`]: #dns_dns_resolveptr_hostname_callback
 [`dns.resolveSoa()`]: #dns_dns_resolvesoa_hostname_callback
+[`dns.resolveSrv()`]: #dns_dns_resolvesrv_hostname_callback
+[`dns.resolveTxt()`]: #dns_dns_resolvetxt_hostname_callback
 [`Error`]: errors.html#errors_class_error
 [Implementation considerations section]: #dns_implementation_considerations
 [supported `getaddrinfo` flags]: #dns_supported_getaddrinfo_flags

From 494bfc00510b5354e0c3a450c7faebf54f117d88 Mon Sep 17 00:00:00 2001
From: Roman Reiss <me@silverwind.io>
Date: Wed, 12 Apr 2017 19:09:26 +0200
Subject: [PATCH 2/6] lowercase primitives

---
 doc/api/dns.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/doc/api/dns.md b/doc/api/dns.md
index 8e879f0a4f3c80..74d00a66af4375 100644
--- a/doc/api/dns.md
+++ b/doc/api/dns.md
@@ -178,16 +178,16 @@ array of the resource records, specified by `rrtype` (resource record type):
 
 | `rrtype`  | Return array contains          | Result type | Shorthand method         |
 |-----------|--------------------------------|-------------|--------------------------|
-| `'A'`     | IPv4 addresses (default)       | {String}    | [`dns.resolve4()`][]     |
-| `'AAAA'`  | IPv6 addresses                 | {String}    | [`dns.resolve6()`][]     |
-| `'CNAME'` | canonical name records         | {String}    | [`dns.resolveCname()`][] |
+| `'A'`     | IPv4 addresses (default)       | {string}    | [`dns.resolve4()`][]     |
+| `'AAAA'`  | IPv6 addresses                 | {string}    | [`dns.resolve6()`][]     |
+| `'CNAME'` | canonical name records         | {string}    | [`dns.resolveCname()`][] |
 | `'MX'`    | mail exchange records          | {Object}    | [`dns.resolveMx()`][]    |
 | `'NAPTR'` | name authority pointer records | {Object}    | [`dns.resolveNaptr()`][] |
-| `'NS'`    | name server records            | {String}    | [`dns.resolveNs()`][]    |
-| `'PTR'`   | pointer records                | {String}    | [`dns.resolvePtr()`][]   |
+| `'NS'`    | name server records            | {string}    | [`dns.resolveNs()`][]    |
+| `'PTR'`   | pointer records                | {string}    | [`dns.resolvePtr()`][]   |
 | `'SOA'`   | start of authority records     | {Object}    | [`dns.resolveSoa()`][]   |
 | `'SRV'`   | service records                | {Object}    | [`dns.resolveSrv()`][]   |
-| `'TXT'`   | text records                   | {String}    | [`dns.resolveTxt()`][]   |
+| `'TXT'`   | text records                   | {string}    | [`dns.resolveTxt()`][]   |
 
 The `callback` function has arguments `(err, addresses)`. When successful,
 `addresses` will be an array of results.

From 17adad8a0808dac2f094963b749579d14b6fd290 Mon Sep 17 00:00:00 2001
From: Roman Reiss <me@silverwind.io>
Date: Wed, 12 Apr 2017 19:36:06 +0200
Subject: [PATCH 3/6] tools: handle tables in doctool

---
 tools/doc/html.js | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/tools/doc/html.js b/tools/doc/html.js
index 38031b4c80fe38..e6596640dc3d4e 100644
--- a/tools/doc/html.js
+++ b/tools/doc/html.js
@@ -183,13 +183,31 @@ function analyticsScript(analytics) {
   `;
 }
 
+// replace placeholders in text tokens
+function replaceInText(text) {
+  return linkJsTypeDocs(linkManPages(text));
+}
+
 // handle general body-text replacements
 // for example, link man page references to the actual page
 function parseText(lexed) {
   lexed.forEach(function(tok) {
     if (tok.text && tok.type !== 'code') {
-      tok.text = linkManPages(tok.text);
-      tok.text = linkJsTypeDocs(tok.text);
+      tok.text = replaceInText(tok.text);
+    } else if (tok.cells) {
+      tok.cells.forEach((row, x) => {
+        row.forEach((_, y) => {
+          if (tok.cells[x] && tok.cells[x][y]) {
+            tok.cells[x][y] = replaceInText(tok.cells[x][y]);
+          }
+        });
+      });
+    } else if (tok.header) {
+      tok.headers.forEach((_, i) => {
+        if (tok.headers[i]) {
+          tok.headers[i] = replaceInText(tok.headers[i]);
+        }
+      });
     }
   });
 }

From d7d220cbbd3c49051413cc881abd76b90dde7c89 Mon Sep 17 00:00:00 2001
From: Roman Reiss <me@silverwind.io>
Date: Wed, 12 Apr 2017 19:46:51 +0200
Subject: [PATCH 4/6] fix header replacements

---
 tools/doc/html.js | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/tools/doc/html.js b/tools/doc/html.js
index e6596640dc3d4e..d4cc2e638f4fb3 100644
--- a/tools/doc/html.js
+++ b/tools/doc/html.js
@@ -194,7 +194,9 @@ function parseText(lexed) {
   lexed.forEach(function(tok) {
     if (tok.text && tok.type !== 'code') {
       tok.text = replaceInText(tok.text);
-    } else if (tok.cells) {
+    }
+
+    if (tok.cells) {
       tok.cells.forEach((row, x) => {
         row.forEach((_, y) => {
           if (tok.cells[x] && tok.cells[x][y]) {
@@ -202,7 +204,9 @@ function parseText(lexed) {
           }
         });
       });
-    } else if (tok.header) {
+    }
+
+    if (tok.header) {
       tok.headers.forEach((_, i) => {
         if (tok.headers[i]) {
           tok.headers[i] = replaceInText(tok.headers[i]);

From 3a1292de7d04fb6ab41a25bb2c25763732b00560 Mon Sep 17 00:00:00 2001
From: Roman Reiss <me@silverwind.io>
Date: Wed, 12 Apr 2017 19:51:48 +0200
Subject: [PATCH 5/6] refactor token parsers slightly, add {Array} in table
 header

---
 doc/api/dns.md    |  2 +-
 tools/doc/html.js | 34 +++++++++++++++++-----------------
 2 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/doc/api/dns.md b/doc/api/dns.md
index 74d00a66af4375..ba2cf8f88749f0 100644
--- a/doc/api/dns.md
+++ b/doc/api/dns.md
@@ -176,7 +176,7 @@ added: v0.1.27
 Uses the DNS protocol to resolve a hostname (e.g. `'nodejs.org'`) into an
 array of the resource records, specified by `rrtype` (resource record type):
 
-| `rrtype`  | Return array contains          | Result type | Shorthand method         |
+| `rrtype`  | Return {Array} contains        | Result type | Shorthand method         |
 |-----------|--------------------------------|-------------|--------------------------|
 | `'A'`     | IPv4 addresses (default)       | {string}    | [`dns.resolve4()`][]     |
 | `'AAAA'`  | IPv6 addresses                 | {string}    | [`dns.resolve6()`][]     |
diff --git a/tools/doc/html.js b/tools/doc/html.js
index d4cc2e638f4fb3..8a071b2e46fc42 100644
--- a/tools/doc/html.js
+++ b/tools/doc/html.js
@@ -192,26 +192,26 @@ function replaceInText(text) {
 // for example, link man page references to the actual page
 function parseText(lexed) {
   lexed.forEach(function(tok) {
-    if (tok.text && tok.type !== 'code') {
-      tok.text = replaceInText(tok.text);
-    }
+    if (tok.type === 'table') {
+      if (tok.cells) {
+        tok.cells.forEach((row, x) => {
+          row.forEach((_, y) => {
+            if (tok.cells[x] && tok.cells[x][y]) {
+              tok.cells[x][y] = replaceInText(tok.cells[x][y]);
+            }
+          });
+        });
+      }
 
-    if (tok.cells) {
-      tok.cells.forEach((row, x) => {
-        row.forEach((_, y) => {
-          if (tok.cells[x] && tok.cells[x][y]) {
-            tok.cells[x][y] = replaceInText(tok.cells[x][y]);
+      if (tok.header) {
+        tok.header.forEach((_, i) => {
+          if (tok.header[i]) {
+            tok.header[i] = replaceInText(tok.header[i]);
           }
         });
-      });
-    }
-
-    if (tok.header) {
-      tok.headers.forEach((_, i) => {
-        if (tok.headers[i]) {
-          tok.headers[i] = replaceInText(tok.headers[i]);
-        }
-      });
+      }
+    } else if (tok.text && tok.type !== 'code') {
+      tok.text = replaceInText(tok.text);
     }
   });
 }

From 50c4789f8d172bfeb72b835cb8d057177758ff5f Mon Sep 17 00:00:00 2001
From: Roman Reiss <me@silverwind.io>
Date: Mon, 17 Apr 2017 12:49:10 +0200
Subject: [PATCH 6/6] rename addresses to records, consolidate paragraphs

---
 doc/api/dns.md | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/doc/api/dns.md b/doc/api/dns.md
index ba2cf8f88749f0..b667d7d6f034b5 100644
--- a/doc/api/dns.md
+++ b/doc/api/dns.md
@@ -167,16 +167,18 @@ dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
 <!-- YAML
 added: v0.1.27
 -->
-- `hostname` {string}
-- `rrtype` {string}
+- `hostname` {string} Hostname to resolve.
+- `rrtype` {string} Resource record type. Default: `'A'`.
 - `callback` {Function}
   - `err` {Error}
-  - `addresses` {string[] | Object[] | string[][] | Object}
+  - `records` {string[] | Object[] | string[][] | Object}
 
-Uses the DNS protocol to resolve a hostname (e.g. `'nodejs.org'`) into an
-array of the resource records, specified by `rrtype` (resource record type):
+Uses the DNS protocol to resolve a hostname (e.g. `'nodejs.org'`) into an array
+of the resource records. The `callback` function has arguments
+`(err, records)`. When successful, `records` will be an array of resource
+records. The type and structure of individual results varies based on `rrtype`:
 
-| `rrtype`  | Return {Array} contains        | Result type | Shorthand method         |
+|  `rrtype` | `records` contains             | Result type | Shorthand method         |
 |-----------|--------------------------------|-------------|--------------------------|
 | `'A'`     | IPv4 addresses (default)       | {string}    | [`dns.resolve4()`][]     |
 | `'AAAA'`  | IPv6 addresses                 | {string}    | [`dns.resolve6()`][]     |
@@ -189,9 +191,6 @@ array of the resource records, specified by `rrtype` (resource record type):
 | `'SRV'`   | service records                | {Object}    | [`dns.resolveSrv()`][]   |
 | `'TXT'`   | text records                   | {string}    | [`dns.resolveTxt()`][]   |
 
-The `callback` function has arguments `(err, addresses)`. When successful,
-`addresses` will be an array of results.
-
 On error, `err` is an [`Error`][] object, where `err.code` is one of the
 [DNS error codes](#dns_error_codes).