update `max-delegation-servers` documentation

Clarify how `max-delegation-servers` is used in the resolver, in
particular, the fact that it, in practice, caps the maximum outgoing
queries to resolve a name at a given delegation point.

diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst
index a42a08d3264ff57bb0f3025a7a6e2ed412cf3956..10ba133ef1c4a792122a242d5df14c424ce631df 100644 (file)
--- a/doc/arm/reference.rst
+++ b/doc/arm/reference.rst
@@ -4187,14 +4187,11 @@ Tuning
 
 .. namedconf:statement:: max-delegation-servers
    :tags: server
-   :short: Configure the maximum number of nameserver names considered for a delegation
+   :short: Configure the maximum number of nameservers considered for a delegation
 
    When looking up remote nameservers for a delegation, the list of nameserver
    names is sorted according to Canonical RR Ordering within an RRset (see
-   :rfc:`4034` Section 6.3), and the number of names for which :iscman:`named`
-   looks up IP addresses is capped at :any:`max-delegation-servers`.
-
-   This capped list of nameserver names is then randomly shuffled every time
+   :rfc:`4034` Section 6.3). This list is then randomly shuffled every time
    :iscman:`named` needs additional remote addresses for those nameservers.
    This randomized selection works around situations where the first few
    nameserver names in the zone are unresponsive.
@@ -4207,6 +4204,12 @@ Tuning
    outgoing DNS query is initiated only if the DNS resolver does not already have
    existing IP addresses for any of the nameserver names in the cache.
 
+   The known NS addresses for an NS name (cached from a previous resolution, or
+   the NS name has glues, or it is defined from a local zone or hints) are
+   counted as delegation servers. Thus, the maximum queries the resolver does
+   to resolve a name at a delegation point is capped at
+   :any:`max-delegation-servers`.
+
    The default and recommended value is ``13``. This limit prevents excessive
    resource use while processing large or misconfigured delegations. The default
    value should only be increased in controlled environments where a remote