From 40d363d2bc31c1d454d2a248189684e1b9964c8b Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 25 Dec 2019 04:56:38 -0800 Subject: [PATCH] doc: improve dns introduction The introductory paragraphs for the `dns` module do not explain what the module is for. Add a short (two brief sentences) explanation. It also emphasizes that functions in the dns module are divided into two categories, but that there is only one function in one of the categories, making the whole categories thing a bit odd to emphasize. Keep the material about the distinctions without discussing categories. There are other incidental revisions (changing an example IP to `example.org` and so on). PR-URL: https://github.com/nodejs/node/pull/31090 Reviewed-By: Colin Ihrig Reviewed-By: James M Snell Reviewed-By: Luigi Pinca Reviewed-By: Trivikram Kamat --- doc/api/dns.md | 86 +++++++++++++++++++++++--------------------------- 1 file changed, 39 insertions(+), 47 deletions(-) diff --git a/doc/api/dns.md b/doc/api/dns.md index eac4bb3ec9588e..6c7f29cfaf0f85 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -4,59 +4,51 @@ > Stability: 2 - Stable -The `dns` module contains functions belonging to two different categories: +The `dns` module enables name resolution. For example, use it to look up IP +addresses of host names. -1. Functions that use the underlying operating system facilities to perform - name resolution, and that do not necessarily perform any network - communication. - This category contains only one function: [`dns.lookup()`][]. **Developers - looking to perform name resolution in the same way that other applications - on the same operating system behave should use [`dns.lookup()`][].** +Although named for the Domain Name System (DNS), it does not always use the DNS +protocol for lookups. [`dns.lookup()`][] uses the operating system facilities to +perform name resolution. It may not need to perform any network communication. +Developers looking to perform name resolution in the same way that other +applications on the same operating system behave should use [`dns.lookup()`][]. - For example, looking up `iana.org`. +```js +const dns = require('dns'); - ```js - const dns = require('dns'); +dns.lookup('example.org', (err, address, family) => { + console.log('address: %j family: IPv%s', address, family); +}); +// address: "93.184.216.34" family: IPv4 +``` - dns.lookup('iana.org', (err, address, family) => { - console.log('address: %j family: IPv%s', address, family); - }); - // address: "192.0.43.8" family: IPv4 - ``` - -2. Functions that connect to an actual DNS server to perform name resolution, - and that _always_ use the network to perform DNS queries. This category - contains all functions in the `dns` module _except_ [`dns.lookup()`][]. - These functions do not use the same set of configuration files used by - [`dns.lookup()`][] (e.g. `/etc/hosts`). These functions should be used by - developers who do not want to use the underlying operating system's - facilities for name resolution, and instead want to _always_ perform DNS - queries. - - Below is an example that resolves `'archive.org'` then reverse resolves the - IP addresses that are returned. - - ```js - const dns = require('dns'); - - dns.resolve4('archive.org', (err, addresses) => { - if (err) throw err; - - console.log(`addresses: ${JSON.stringify(addresses)}`); - - addresses.forEach((a) => { - dns.reverse(a, (err, hostnames) => { - if (err) { - throw err; - } - console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`); - }); - }); +All other functions in the `dns` module connect to an actual DNS server to +perform name resolution. They will always use the network to perform DNS +queries. These functions do not use the same set of configuration files used by +[`dns.lookup()`][] (e.g. `/etc/hosts`). These functions should be used by +developers who do not want to use the underlying operating system's +facilities for name resolution, and instead want to always perform DNS queries. + +```js +const dns = require('dns'); + +dns.resolve4('archive.org', (err, addresses) => { + if (err) throw err; + + console.log(`addresses: ${JSON.stringify(addresses)}`); + + addresses.forEach((a) => { + dns.reverse(a, (err, hostnames) => { + if (err) { + throw err; + } + console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`); }); - ``` + }); +}); +``` -There are subtle consequences in choosing one over the other, please consult -the [Implementation considerations section][] for more information. +See the [Implementation considerations section][] for more information. ## Class: `dns.Resolver`