-
Notifications
You must be signed in to change notification settings - Fork 29.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: clarify the callback arguments of dns.resolve #9532
Conversation
477772c
to
df695fe
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A couple of nits, but LGTM
doc/api/dns.md
Outdated
[`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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
FWIW, I also think the new wording is a little ambiguous.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Right, I'll put the part about addresses
back.
doc/api/dns.md
Outdated
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). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nit: Avoid here
as link text. Maybe ...one of the error codes listed under [DNS error codes].
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How about a concise where err.code is one of the [error codes].
?
doc/api/dns.md
Outdated
[`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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
FWIW, I also think the new wording is a little ambiguous.
28e1a05
to
701cdc2
Compare
doc/api/dns.md
Outdated
[`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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IP addresses, hostnames (for CNAME) or text (for TXT). You think we should go into su much detail here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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!
I'll have to revise again, |
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. |
doc/api/dns.md
Outdated
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). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Simply saying "err.code is one of the error codes" sounds vague. Perhaps specifying "DNS error codes" would be a bit better?
@bnoordhuis ... has this been updated to your satisfaction? |
This is still WIP! |
2a5ae53
to
a668f38
Compare
a668f38
to
f752a00
Compare
doc/api/dns.md
Outdated
[`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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Could call this results
so it's consistent with the table above. After all, not all results are addresses.
ping @bnoordhuis |
I'll look into fixing this type bug in the doctool, but would appreciate feedback on the table here! |
f752a00
to
0ad3652
Compare
ping @silverwind @bnoordhuis ... updates on this? |
Still got to investigate why |
0ad3652
to
f690863
Compare
PR-URL: #9532 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>
PR-URL: #9532 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>
PR-URL: #9532 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>
PR-URL: #9532 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>
PR-URL: #9532 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>
PR-URL: #9532 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>
This doesn't land cleanly, could you backport to v6.x if appropriate? |
Let's land #13054 on v6.x first, I think it may land cleanly then. |
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? |
Backport in #13073 |
PR-URL: nodejs#9532 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>
PR-URL: nodejs#9532 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com>
Checklist
Affected core subsystem(s)
doc
Description of change
Shortened and clarfied the callback arguments of
dns.resolve
. The fact that theMX
rrtype was also returning a object was missing entirely.