From: Bob Halley <halley@dnspython.org>
Date: Mon, 16 Jan 2017 16:27:37 +0000 (-0800)
Subject: doco answer
X-Git-Tag: v1.16.0~51
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1eb29e99939ad511aa6db1de22b94c8efabb2c69;p=thirdparty%2Fdnspython.git

doco answer
---

diff --git a/dns/resolver.py b/dns/resolver.py
index 4ba171fe..ca76a4b4 100644
--- a/dns/resolver.py
+++ b/dns/resolver.py
@@ -13,10 +13,7 @@
 # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
 # OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-"""DNS stub resolver.
-
-@var default_resolver: The default resolver object
-@type default_resolver: dns.resolver.Resolver object"""
+"""DNS stub resolver."""
 
 import socket
 import sys
@@ -163,34 +160,19 @@ class NoMetaqueries(dns.exception.DNSException):
 
 
 class Answer(object):
-    """DNS stub resolver answer
+    """DNS stub resolver answer.
 
     Instances of this class bundle up the result of a successful DNS
     resolution.
 
     For convenience, the answer object implements much of the sequence
-    protocol, forwarding to its rrset.  E.g. "for a in answer" is
-    equivalent to "for a in answer.rrset", "answer[i]" is equivalent
-    to "answer.rrset[i]", and "answer[i:j]" is equivalent to
-    "answer.rrset[i:j]".
+    protocol, forwarding to its ``rrset`` attribute.  E.g.
+    ``for a in answer`` is equivalent to ``for a in answer.rrset``.
+    ``answer[i]`` is equivalent to ``answer.rrset[i]``, and
+    ``answer[i:j]`` is equivalent to ``answer.rrset[i:j]``.
 
     Note that CNAMEs or DNAMEs in the response may mean that answer
-    node's name might not be the query name.
-
-    @ivar qname: The query name
-    @type qname: dns.name.Name object
-    @ivar rdtype: The query type
-    @type rdtype: int
-    @ivar rdclass: The query class
-    @type rdclass: int
-    @ivar response: The response message
-    @type response: dns.message.Message object
-    @ivar rrset: The answer
-    @type rrset: dns.rrset.RRset object
-    @ivar expiration: The time when the answer expires
-    @type expiration: float (seconds since the epoch)
-    @ivar canonical_name: The canonical name of the query name
-    @type canonical_name: dns.name.Name object
+    RRset's name might not be the query name.
     """
 
     def __init__(self, qname, rdtype, rdclass, response,
@@ -1091,6 +1073,8 @@ class Resolver(object):
         @type flags: int"""
         self.flags = flags
 
+
+#: The default resolver.
 default_resolver = None
 
 
@@ -1104,8 +1088,10 @@ def get_default_resolver():
 def reset_default_resolver():
     """Re-initialize default resolver.
 
-    resolv.conf will be re-read immediatelly.
+    Note that the resolver configuration (i.e. /etc/resolv.conf on UNIX
+    systems) will be re-read immediately.
     """
+
     global default_resolver
     default_resolver = Resolver()
 
diff --git a/doc/resolver-class.rst b/doc/resolver-class.rst
index a5b6c0a4..f6e05086 100644
--- a/doc/resolver-class.rst
+++ b/doc/resolver-class.rst
@@ -14,3 +14,33 @@ The dns.resolver.Resolver and dns.resolver.Answer Classes
 
 .. autoclass:: dns.resolver.Answer
    :members:
+
+   .. attribute:: qname
+
+      A ``dns.name.Name``, the query name.
+
+   .. attribute:: rdclass
+
+      An ``int``, the query class.
+
+   .. attribute:: rdtype
+
+      An ``int``, the query type.
+
+   .. attribute:: response
+
+      A ``dns.message.Message``, the response message.
+
+   .. attribute:: rrset
+
+      A ``dns.rrset.RRset`` or ``None``, the answer RRset.
+
+   .. attribute:: expiration
+
+      A ``float``, the time when the answer expires.
+
+   .. attribute:: canonical_name
+
+      A ``dns.name.Name``, the canonical name of the query name,
+      i.e. the owner name of the answer RRset after any CNAME and DNAME
+      chaining.
diff --git a/doc/resolver-functions.rst b/doc/resolver-functions.rst
index e4ec1ea7..d3c5dccc 100644
--- a/doc/resolver-functions.rst
+++ b/doc/resolver-functions.rst
@@ -1,9 +1,10 @@
 .. _resolver-functions:
 
-Resolver Functions
-==================
+Resolver Functions and The Default Resolver
+===========================================
 
 .. autofunction:: dns.resolver.query
 .. autofunction:: dns.resolver.zone_for_name
+.. autodata:: dns.resolver.default_resolver
 .. autofunction:: dns.resolver.get_default_resolver
 .. autofunction:: dns.resolver.reset_default_resolver
diff --git a/doc/resolver.rst b/doc/resolver.rst
index e394d2ef..7068bd30 100644
--- a/doc/resolver.rst
+++ b/doc/resolver.rst
@@ -9,5 +9,6 @@ This is a placeholder.
 .. toctree::
 
    resolver-class
+   resolver-functions
    resolver-caching
    resolver-override