doc: Clean up README and doc.go (#817)

Cleans this up a bit.

Signed-off-by: Miek Gieben <miek@miek.nl>

README.md

@@ -7,10 +7,10 @@
 
 > Less is more.
 
-Complete and usable DNS library. All widely used Resource Records are supported, including the
+Complete and usable DNS library. All Resource Records are supported, including the DNSSEC types.
-DNSSEC types. It follows a lean and mean philosophy. If there is stuff you should know as a DNS
+It follows a lean and mean philosophy. If there is stuff you should know as a DNS programmer there
-programmer there isn't a convenience function for it. Server side and client side programming is
+isn't a convenience function for it. Server side and client side programming is supported, i.e. you
-supported, i.e. you can build servers and resolvers with it.
+can build servers and resolvers with it.
 
 We try to keep the "master" branch as sane as possible and at the bleeding edge of standards,
 avoiding breaking changes wherever reasonable. We support the last two versions of Go.
@@ -42,10 +42,9 @@ A not-so-up-to-date-list-that-may-be-actually-current:
 * https://github.com/tianon/rawdns
 * https://mesosphere.github.io/mesos-dns/
 * https://pulse.turbobytes.com/
-* https://play.google.com/store/apps/details?id=com.turbobytes.dig
 * https://github.com/fcambus/statzone
 * https://github.com/benschw/dns-clb-go
-* https://github.com/corny/dnscheck for http://public-dns.info/
+* https://github.com/corny/dnscheck for <http://public-dns.info/>
 * https://namesmith.io
 * https://github.com/miekg/unbound
 * https://github.com/miekg/exdns
@@ -56,7 +55,7 @@ A not-so-up-to-date-list-that-may-be-actually-current:
 * https://github.com/bamarni/dockness
 * https://github.com/fffaraz/microdns
 * http://kelda.io
-* https://github.com/ipdcode/hades (JD.COM)
+* https://github.com/ipdcode/hades <https://jd.com>
 * https://github.com/StackExchange/dnscontrol/
 * https://www.dnsperf.com/
 * https://dnssectest.net/
@@ -73,24 +72,22 @@ Send pull request if you want to be listed here.
 
 # Features
 
-* UDP/TCP queries, IPv4 and IPv6;
+* UDP/TCP queries, IPv4 and IPv6
-* RFC 1035 zone file parsing ($INCLUDE, $ORIGIN, $TTL and $GENERATE (for all record types) are supported;
+* RFC 1035 zone file parsing ($INCLUDE, $ORIGIN, $TTL and $GENERATE (for all record types) are supported
-* Fast:
+* Fast
-    * Reply speed around ~ 80K qps (faster hardware results in more qps);
+* Server side programming (mimicking the net/http package)
-    * Parsing RRs ~ 100K RR/s, that's 5M records in about 50 seconds;
+* Client side programming
-* Server side programming (mimicking the net/http package);
+* DNSSEC: signing, validating and key generation for DSA, RSA, ECDSA and Ed25519
-* Client side programming;
+* EDNS0, NSID, Cookies
-* DNSSEC: signing, validating and key generation for DSA, RSA, ECDSA and Ed25519;
+* AXFR/IXFR
-* EDNS0, NSID, Cookies;
+* TSIG, SIG(0)
-* AXFR/IXFR;
+* DNS over TLS (DoT): encrypted connection between client and server over TCP
-* TSIG, SIG(0);
+* DNS name compression
-* DNS over TLS: optional encrypted connection between client and server;
-* DNS name compression;
-* Depends only on the standard library.
 
 Have fun!
 
 Miek Gieben  -  2010-2012  -  <miek@miek.nl>
+DNS Authors 2012-
 
 # Building
 
@@ -164,9 +161,9 @@ Example programs can be found in the `github.com/miekg/exdns` repository.
 * 7873 - Domain Name System (DNS) Cookies (draft-ietf-dnsop-cookies)
 * 8080 - EdDSA for DNSSEC
 
-## Loosely based upon
+## Loosely Based Upon
 
-* `ldns`
+* ldns - <https://nlnetlabs.nl/projects/ldns/about/>
-* `NSD`
+* NSD - <https://nlnetlabs.nl/projects/nsd/about/>
-* `Net::DNS`
+* Net::DNS - <http://www.net-dns.org/>
-* `GRONG`
+* GRONG - <https://github.com/bortzmeyer/grong>

doc.go

@@ -1,20 +1,20 @@
 /*
 Package dns implements a full featured interface to the Domain Name System.
-Server- and client-side programming is supported.
+Both server- and client-side programming is supported. The package allows
-The package allows complete control over what is sent out to the DNS. The package
+complete control over what is sent out to the DNS. The API follows the
-API follows the less-is-more principle, by presenting a small, clean interface.
+less-is-more principle, by presenting a small, clean interface.
 
-The package dns supports (asynchronous) querying/replying, incoming/outgoing zone transfers,
+It supports (asynchronous) querying/replying, incoming/outgoing zone transfers,
 TSIG, EDNS0, dynamic updates, notifies and DNSSEC validation/signing.
-Note that domain names MUST be fully qualified, before sending them, unqualified
+
+Note that domain names MUST be fully qualified before sending them, unqualified
 names in a message will result in a packing failure.
 
-Resource records are native types. They are not stored in wire format.
+Resource records are native types. They are not stored in wire format. Basic
-Basic usage pattern for creating a new resource record:
+usage pattern for creating a new resource record:
 
      r := new(dns.MX)
-     r.Hdr = dns.RR_Header{Name: "miek.nl.", Rrtype: dns.TypeMX,
+     r.Hdr = dns.RR_Header{Name: "miek.nl.", Rrtype: dns.TypeMX, Class: dns.ClassINET, Ttl: 3600}
-     Class: dns.ClassINET, Ttl: 3600}
      r.Preference = 10
      r.Mx = "mx.miek.nl."
 
@@ -30,8 +30,8 @@ Or even:
 
      mx, err := dns.NewRR("$ORIGIN nl.\nmiek 1H IN MX 10 mx.miek")
 
-In the DNS messages are exchanged, these messages contain resource
+In the DNS messages are exchanged, these messages contain resource records
-records (sets). Use pattern for creating a message:
+(sets). Use pattern for creating a message:
 
      m := new(dns.Msg)
      m.SetQuestion("miek.nl.", dns.TypeMX)
@@ -40,8 +40,8 @@ Or when not certain if the domain name is fully qualified:
 
 	m.SetQuestion(dns.Fqdn("miek.nl"), dns.TypeMX)
 
-The message m is now a message with the question section set to ask
+The message m is now a message with the question section set to ask the MX
-the MX records for the miek.nl. zone.
+records for the miek.nl. zone.
 
 The following is slightly more verbose, but more flexible:
 
@@ -51,9 +51,8 @@ The following is slightly more verbose, but more flexible:
      m1.Question = make([]dns.Question, 1)
      m1.Question[0] = dns.Question{"miek.nl.", dns.TypeMX, dns.ClassINET}
 
-After creating a message it can be sent.
+After creating a message it can be sent. Basic use pattern for synchronous
-Basic use pattern for synchronous querying the DNS at a
+querying the DNS at a server configured on 127.0.0.1 and port 53:
-server configured on 127.0.0.1 and port 53:
 
      c := new(dns.Client)
      in, rtt, err := c.Exchange(m1, "127.0.0.1:53")
@@ -99,25 +98,24 @@ the Answer section:
 
 Domain Name and TXT Character String Representations
 
-Both domain names and TXT character strings are converted to presentation
+Both domain names and TXT character strings are converted to presentation form
-form both when unpacked and when converted to strings.
+both when unpacked and when converted to strings.
 
 For TXT character strings, tabs, carriage returns and line feeds will be
-converted to \t, \r and \n respectively. Back slashes and quotations marks
+converted to \t, \r and \n respectively. Back slashes and quotations marks will
-will be escaped. Bytes below 32 and above 127 will be converted to \DDD
+be escaped. Bytes below 32 and above 127 will be converted to \DDD form.
-form.
 
-For domain names, in addition to the above rules brackets, periods,
+For domain names, in addition to the above rules brackets, periods, spaces,
-spaces, semicolons and the at symbol are escaped.
+semicolons and the at symbol are escaped.
 
 DNSSEC
 
-DNSSEC (DNS Security Extension) adds a layer of security to the DNS. It
+DNSSEC (DNS Security Extension) adds a layer of security to the DNS. It uses
-uses public key cryptography to sign resource records. The
+public key cryptography to sign resource records. The public keys are stored in
-public keys are stored in DNSKEY records and the signatures in RRSIG records.
+DNSKEY records and the signatures in RRSIG records.
 
-Requesting DNSSEC information for a zone is done by adding the DO (DNSSEC OK) bit
+Requesting DNSSEC information for a zone is done by adding the DO (DNSSEC OK)
-to a request.
+bit to a request.
 
      m := new(dns.Msg)
      m.SetEdns0(4096, true)
@@ -126,9 +124,9 @@ Signature generation, signature verification and key generation are all supporte
 
 DYNAMIC UPDATES
 
-Dynamic updates reuses the DNS message format, but renames three of
+Dynamic updates reuses the DNS message format, but renames three of the
-the sections. Question is Zone, Answer is Prerequisite, Authority is
+sections. Question is Zone, Answer is Prerequisite, Authority is Update, only
-Update, only the Additional is not renamed. See RFC 2136 for the gory details.
+the Additional is not renamed. See RFC 2136 for the gory details.
 
 You can set a rather complex set of rules for the existence of absence of
 certain resource records or names in a zone to specify if resource records
@@ -145,10 +143,9 @@ DNS function shows which functions exist to specify the prerequisites.
   NONE     rrset    empty    RRset does not exist       dns.RRsetNotUsed
   zone     rrset    rr       RRset exists (value dep)   dns.Used
 
-The prerequisite section can also be left empty.
+The prerequisite section can also be left empty. If you have decided on the
-If you have decided on the prerequisites you can tell what RRs should
+prerequisites you can tell what RRs should be added or deleted. The next table
-be added or deleted. The next table shows the options you have and
+shows the options you have and what functions to call.
-what functions to call.
 
  3.4.2.6 - Table Of Metavalues Used In Update Section
 
@@ -181,10 +178,10 @@ changes to the RRset after calling SetTsig() the signature will be incorrect.
 	...
 	// When sending the TSIG RR is calculated and filled in before sending
 
-When requesting an zone transfer (almost all TSIG usage is when requesting zone transfers), with
+When requesting an zone transfer (almost all TSIG usage is when requesting zone
-TSIG, this is the basic use pattern. In this example we request an AXFR for
+transfers), with TSIG, this is the basic use pattern. In this example we
-miek.nl. with TSIG key named "axfr." and secret "so6ZGir4GPAqINNh9U5c3A=="
+request an AXFR for miek.nl. with TSIG key named "axfr." and secret
-and using the server 176.58.119.54:
+"so6ZGir4GPAqINNh9U5c3A==" and using the server 176.58.119.54:
 
 	t := new(dns.Transfer)
 	m := new(dns.Msg)
@@ -194,8 +191,8 @@ and using the server 176.58.119.54:
 	c, err := t.In(m, "176.58.119.54:53")
 	for r := range c { ... }
 
-You can now read the records from the transfer as they come in. Each envelope is checked with TSIG.
+You can now read the records from the transfer as they come in. Each envelope
-If something is not correct an error is returned.
+is checked with TSIG. If something is not correct an error is returned.
 
 Basic use pattern validating and replying to a message that has TSIG set.
 
@@ -220,29 +217,30 @@ Basic use pattern validating and replying to a message that has TSIG set.
 
 PRIVATE RRS
 
-RFC 6895 sets aside a range of type codes for private use. This range
+RFC 6895 sets aside a range of type codes for private use. This range is 65,280
-is 65,280 - 65,534 (0xFF00 - 0xFFFE). When experimenting with new Resource Records these
+- 65,534 (0xFF00 - 0xFFFE). When experimenting with new Resource Records these
 can be used, before requesting an official type code from IANA.
 
-see http://miek.nl/2014/September/21/idn-and-private-rr-in-go-dns/ for more
+See https://miek.nl/2014/September/21/idn-and-private-rr-in-go-dns/ for more
 information.
 
 EDNS0
 
-EDNS0 is an extension mechanism for the DNS defined in RFC 2671 and updated
+EDNS0 is an extension mechanism for the DNS defined in RFC 2671 and updated by
-by RFC 6891. It defines an new RR type, the OPT RR, which is then completely
+RFC 6891. It defines an new RR type, the OPT RR, which is then completely
 abused.
+
 Basic use pattern for creating an (empty) OPT RR:
 
 	o := new(dns.OPT)
 	o.Hdr.Name = "." // MUST be the root zone, per definition.
 	o.Hdr.Rrtype = dns.TypeOPT
 
-The rdata of an OPT RR consists out of a slice of EDNS0 (RFC 6891)
+The rdata of an OPT RR consists out of a slice of EDNS0 (RFC 6891) interfaces.
-interfaces. Currently only a few have been standardized: EDNS0_NSID
+Currently only a few have been standardized: EDNS0_NSID (RFC 5001) and
-(RFC 5001) and EDNS0_SUBNET (draft-vandergaast-edns-client-subnet-02). Note
+EDNS0_SUBNET (draft-vandergaast-edns-client-subnet-02). Note that these options
-that these options may be combined in an OPT RR.
+may be combined in an OPT RR. Basic use pattern for a server to check if (and
-Basic use pattern for a server to check if (and which) options are set:
+which) options are set:
 
 	// o is a dns.OPT
 	for _, s := range o.Option {
@@ -262,10 +260,9 @@ From RFC 2931:
     ... protection for glue records, DNS requests, protection for message headers
     on requests and responses, and protection of the overall integrity of a response.
 
-It works like TSIG, except that SIG(0) uses public key cryptography, instead of the shared
+It works like TSIG, except that SIG(0) uses public key cryptography, instead of
-secret approach in TSIG.
+the shared secret approach in TSIG. Supported algorithms: DSA, ECDSAP256SHA256,
-Supported algorithms: DSA, ECDSAP256SHA256, ECDSAP384SHA384, RSASHA1, RSASHA256 and
+ECDSAP384SHA384, RSASHA1, RSASHA256 and RSASHA512.
-RSASHA512.
 
 Signing subsequent messages in multi-message sessions is not implemented.
 */