Document every exported symbol and how callers use the library.

Co-authored-by: Cursor <cursoragent@cursor.com>

client.go

@@ -6,22 +6,31 @@ import (
 	"strings"
 )
 
-// TSIG is caller-supplied key material. go-dns does not generate keys.
+// TSIG is caller-supplied key material. The library does not generate keys
+// or write BIND configuration.
+// Name is the key name presented to the nameserver.
+// Algorithm is a BIND name such as hmac-sha256 (also hmac-md5, hmac-sha1,
+// hmac-sha224, hmac-sha384, and hmac-sha512).
+// Secret is the base64 secret.
 type TSIG struct {
-	Name      string // key name presented to BIND
-	Algorithm string // BIND algorithm name, e.g. hmac-sha256
-	Secret    string // base64 secret from the Key File
+	Name      string
+	Algorithm string
+	Secret    string
 }
 
-// Client is a session against one nameserver and zone, authenticated with TSIG.
+// Client is one session: one nameserver, one zone, and one TSIG key.
+// AXFR and Update both use that key. There is no unsigned mode.
 type Client struct {
 	server string
 	zone   string
 	tsig   TSIG
 }
 
-// NewClient validates ASCII zone names and required TSIG fields.
-// server is host or host:port; port 53 is assumed when omitted.
+// NewClient starts a session for one nameserver, zone, and TSIG key.
+// server is a host or host:port. A missing port becomes 53.
+// An IPv6 host must be written in brackets.
+// It returns an error when server, zone, or any TSIG field is empty,
+// when zone or the key name is not ASCII, or when server is a bare IPv6 address.
 func NewClient(server, zone string, key TSIG) (*Client, error) {
 	if strings.TrimSpace(server) == "" {
 		return nil, fmt.Errorf("server is required")