doc: clarify the callback arguments of dns.resolve #9532

silverwind · 2016-11-09T21:04:33Z

Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc

Description of change

Shortened and clarfied the callback arguments of dns.resolve. The fact that the MX rrtype was also returning a object was missing entirely.

Trott

A couple of nits, but LGTM

Trott · 2016-11-10T06:41:31Z

doc/api/dns.md

-[`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.
+The `callback` function has arguments `(err, addresses)` and will receive an


Nit: I would retain the ". When successful, addreses will be" wording. The revised text says the callback "will receive an array" but it's not immediately clear that the array is addresses. That was clear in the previous wording.

FWIW, I also think the new wording is a little ambiguous.

Right, I'll put the part about addresses back.

Trott · 2016-11-10T06:43:58Z

doc/api/dns.md

-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 error
+codes listed [here](#dns_error_codes).


Nit: Avoid here as link text. Maybe ...one of the error codes listed under [DNS error codes].?

How about a concise where err.code is one of the [error codes].?

bnoordhuis · 2016-11-10T12:34:14Z

doc/api/dns.md

-[`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.
+The `callback` function has arguments `(err, addresses)` and will receive an


FWIW, I also think the new wording is a little ambiguous.

sam-github · 2016-11-10T17:26:14Z

doc/api/dns.md

-[`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. A result will be a string except when


And the string will be.... what? Perhaps in the values enumeration above, it should describe the string format for the record types, and maybe even give an example?

IP addresses, hostnames (for CNAME) or text (for TXT). You think we should go into su much detail here?

I read it, and if was going to use this API, I'd start off by calling it to see what it returns, because it doesn't say. So, yes!

silverwind · 2016-11-10T17:31:05Z

I'll have to revise again, NAPTR queries also return objects. Maybe we should just link to the individual methods below in the list of types to avoid duplication?

sam-github · 2016-11-10T17:42:54Z

Maybe we should just link to the individual methods below in the list of types to avoid duplication?

Excellent idea, yes, if each rtype maps to an API lower down, that describes the string/object format and gives an example, no need to duplicate, linking is great.

Qard · 2016-11-20T08:32:07Z

doc/api/dns.md

-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
+[error codes](#dns_error_codes).


Simply saying "err.code is one of the error codes" sounds vague. Perhaps specifying "DNS error codes" would be a bit better?

jasnell · 2016-12-05T22:46:31Z

@bnoordhuis ... has this been updated to your satisfaction?

silverwind · 2016-12-05T22:51:35Z

This is still WIP!

silverwind · 2016-12-09T19:15:23Z

Reworked this into a table and sorted everything alphabetically. There seems to be an issue that JS types in tables don't get linkified, so it renders like this right now for me:

silverwind · 2016-12-09T19:19:35Z

doc/api/dns.md

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


Could call this results so it's consistent with the table above. After all, not all results are addresses.

jasnell · 2017-01-11T00:27:33Z

ping @bnoordhuis

silverwind · 2017-01-11T17:14:11Z

I'll look into fixing this type bug in the doctool, but would appreciate feedback on the table here!

jasnell · 2017-03-24T22:51:12Z

ping @silverwind @bnoordhuis ... updates on this?

silverwind · 2017-03-26T08:42:05Z

Still got to investigate why {type} does not render correctly in tables.

silverwind · 2017-04-19T17:25:21Z

Thanks! Landed in d33b3d1 and 0584aeb.

PR-URL: #9532 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Rich Trott <[email protected]>

gibfahn · 2017-05-16T12:39:38Z

This doesn't land cleanly, could you backport to v6.x if appropriate?

silverwind · 2017-05-16T15:36:45Z

Let's land #13054 on v6.x first, I think it may land cleanly then.

gibfahn · 2017-05-16T17:25:02Z

Sadly it does not

Conflict on first commit:

++<<<<<<< HEAD
 +
 +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
 +
 +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.
 +
 +On error, `err` is an [`Error`][] object, where `err.code` is
 +one of the error codes listed [here](#dns_error_codes).
++=======
+ - `hostname` {string} Hostname to resolve.
+ - `rrtype` {string} Resource record type. Default: `'A'`.
+ - `callback` {Function}
+   - `err` {Error}
+   - `records` {string[] | Object[] | string[][] | Object}
+ 
+ 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` | `records` 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()`][]   |
+ 
+ On error, `err` is an [`Error`][] object, where `err.code` is one of the
+ [DNS error codes](#dns_error_codes).
++>>>>>>> d33b3d1086... doc: clarify the callback arguments of dns.resolve

Would you be willing to backport?

silverwind · 2017-05-17T05:44:33Z

Backport in #13073

PR-URL: nodejs#9532 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Rich Trott <[email protected]>

PR-URL: #9532 Backport-PR-URL: #13073 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Rich Trott <[email protected]>

nodejs-github-bot added dns Issues and PRs related to the dns subsystem. doc Issues and PRs related to the documentations. labels Nov 9, 2016

silverwind force-pushed the dns-resolve-api branch 2 times, most recently from 477772c to df695fe Compare November 9, 2016 23:34

silverwind changed the title ~~doc: clarify return value of dns.resolve~~ doc: clarify the callback arguments of dns.resolve Nov 9, 2016

Trott approved these changes Nov 10, 2016

View reviewed changes

bnoordhuis requested changes Nov 10, 2016

View reviewed changes

silverwind force-pushed the dns-resolve-api branch from 28e1a05 to 701cdc2 Compare November 10, 2016 17:22

sam-github reviewed Nov 10, 2016

View reviewed changes

Qard reviewed Nov 20, 2016

View reviewed changes

jasnell approved these changes Dec 5, 2016

View reviewed changes

silverwind added the dont-land-on-v7.x label Dec 5, 2016

Fishrock123 removed the dont-land-on-v7.x label Dec 8, 2016

silverwind force-pushed the dns-resolve-api branch 2 times, most recently from 2a5ae53 to a668f38 Compare December 9, 2016 19:14

silverwind force-pushed the dns-resolve-api branch from a668f38 to f752a00 Compare December 9, 2016 19:18

silverwind commented Dec 9, 2016

View reviewed changes

silverwind force-pushed the dns-resolve-api branch from f752a00 to 0ad3652 Compare March 5, 2017 16:09

jasnell added the stalled Issues and PRs that are stalled. label Mar 24, 2017

doc: clarify dns.resolve API

f690863

silverwind force-pushed the dns-resolve-api branch from 0ad3652 to f690863 Compare April 12, 2017 17:06

silverwind closed this Apr 19, 2017

evanlucas pushed a commit that referenced this pull request Apr 25, 2017

doc: clarify the callback arguments of dns.resolve

6cb7dbd

PR-URL: #9532 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Rich Trott <[email protected]>

evanlucas pushed a commit that referenced this pull request Apr 25, 2017

tools: add table parsing capability to the doctool

c61f26e

PR-URL: #9532 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Rich Trott <[email protected]>

evanlucas mentioned this pull request May 1, 2017

v7.10.0 proposal #12775

Merged

evanlucas pushed a commit that referenced this pull request May 1, 2017

doc: clarify the callback arguments of dns.resolve

dd39449

PR-URL: #9532 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Rich Trott <[email protected]>

evanlucas pushed a commit that referenced this pull request May 1, 2017

tools: add table parsing capability to the doctool

5d21203

PR-URL: #9532 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Rich Trott <[email protected]>

evanlucas pushed a commit that referenced this pull request May 2, 2017

doc: clarify the callback arguments of dns.resolve

9250f02

PR-URL: #9532 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Rich Trott <[email protected]>

evanlucas pushed a commit that referenced this pull request May 2, 2017

tools: add table parsing capability to the doctool

13441eb

PR-URL: #9532 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Rich Trott <[email protected]>

gibfahn added the lts-watch-v6.x label May 16, 2017

gibfahn added the backport-requested-v6.x label May 16, 2017

silverwind mentioned this pull request May 16, 2017

(v6.x backport) doc types fixes #13054

Closed

gibfahn added backported-to-v6.x and removed backport-requested-v6.x labels Jun 20, 2017

MylesBorins mentioned this pull request Jul 18, 2017

v6.11.2 proposal #14356

Merged

MylesBorins removed the lts-watch-v6.x label Nov 14, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: clarify the callback arguments of dns.resolve #9532

doc: clarify the callback arguments of dns.resolve #9532

silverwind commented Nov 9, 2016 •

edited

Loading

Trott left a comment

Trott Nov 10, 2016

bnoordhuis Nov 10, 2016

silverwind Nov 10, 2016

Trott Nov 10, 2016

silverwind Nov 10, 2016

bnoordhuis Nov 10, 2016

sam-github Nov 10, 2016

silverwind Nov 10, 2016

sam-github Nov 10, 2016

silverwind commented Nov 10, 2016 •

edited

Loading

sam-github commented Nov 10, 2016

Qard Nov 20, 2016

jasnell commented Dec 5, 2016

silverwind commented Dec 5, 2016

silverwind commented Dec 9, 2016 •

edited

Loading

silverwind Dec 9, 2016

jasnell commented Jan 11, 2017

silverwind commented Jan 11, 2017

jasnell commented Mar 24, 2017

silverwind commented Mar 26, 2017

silverwind commented Apr 19, 2017

gibfahn commented May 16, 2017

silverwind commented May 16, 2017

gibfahn commented May 16, 2017

silverwind commented May 17, 2017

doc: clarify the callback arguments of dns.resolve #9532

doc: clarify the callback arguments of dns.resolve #9532

Conversation

silverwind commented Nov 9, 2016 • edited Loading

Checklist

Affected core subsystem(s)

Description of change

Trott left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

silverwind commented Nov 10, 2016 • edited Loading

sam-github commented Nov 10, 2016

Choose a reason for hiding this comment

jasnell commented Dec 5, 2016

silverwind commented Dec 5, 2016

silverwind commented Dec 9, 2016 • edited Loading

Choose a reason for hiding this comment

jasnell commented Jan 11, 2017

silverwind commented Jan 11, 2017

jasnell commented Mar 24, 2017

silverwind commented Mar 26, 2017

silverwind commented Apr 19, 2017

gibfahn commented May 16, 2017

silverwind commented May 16, 2017

gibfahn commented May 16, 2017

silverwind commented May 17, 2017

silverwind commented Nov 9, 2016 •

edited

Loading

silverwind commented Nov 10, 2016 •

edited

Loading

silverwind commented Dec 9, 2016 •

edited

Loading