From c3b7baab955726cfa7d2b8212707944dba10f48d Mon Sep 17 00:00:00 2001
From: Bob Halley <halley@dnspython.org>
Date: Mon, 16 Jan 2017 08:09:30 -0800
Subject: [PATCH] start resolver doco

---
 dns/resolver.py           | 23 +++++------------------
 doc/exceptions.rst        | 11 +++++++++++
 doc/resolver-class.rst    | 13 +++++++++++++
 doc/resolver-override.rst | 12 ++++++++++++
 doc/resolver.rst          |  4 ++++
 5 files changed, 45 insertions(+), 18 deletions(-)
 create mode 100644 doc/resolver-class.rst
 create mode 100644 doc/resolver-override.rst

diff --git a/dns/resolver.py b/dns/resolver.py
index c647df43..4ba171fe 100644
--- a/dns/resolver.py
+++ b/dns/resolver.py
@@ -49,7 +49,6 @@ if sys.platform == 'win32':
         import _winreg  # pylint: disable=import-error
 
 class NXDOMAIN(dns.exception.DNSException):
-
     """The DNS query name does not exist."""
     supp_kwargs = set(['qnames', 'responses'])
     fmt = None  # we have our own __str__ implementation
@@ -109,7 +108,6 @@ class NXDOMAIN(dns.exception.DNSException):
 
 
 class YXDOMAIN(dns.exception.DNSException):
-
     """The DNS query name is too long after DNAME substitution."""
 
 # The definition of the Timeout exception has moved from here to the
@@ -120,7 +118,6 @@ Timeout = dns.exception.Timeout
 
 
 class NoAnswer(dns.exception.DNSException):
-
     """The DNS response does not contain an answer to the question."""
     fmt = 'The DNS response does not contain an answer ' + \
           'to the question: {query}'
@@ -132,7 +129,6 @@ class NoAnswer(dns.exception.DNSException):
 
 
 class NoNameservers(dns.exception.DNSException):
-
     """All nameservers failed to answer the query.
 
     errors: list of servers and respective errors
@@ -155,22 +151,18 @@ class NoNameservers(dns.exception.DNSException):
 
 
 class NotAbsolute(dns.exception.DNSException):
-
     """An absolute domain name is required but a relative name was provided."""
 
 
 class NoRootSOA(dns.exception.DNSException):
-
     """There is no SOA RR at the DNS root name. This should never happen!"""
 
 
 class NoMetaqueries(dns.exception.DNSException):
-
     """DNS metaqueries are not allowed."""
 
 
 class Answer(object):
-
     """DNS stub resolver answer
 
     Instances of this class bundle up the result of a successful DNS
@@ -289,7 +281,6 @@ class Answer(object):
 
 
 class Cache(object):
-
     """Simple DNS answer cache.
 
     @ivar data: A dictionary of cached data
@@ -387,9 +378,7 @@ class Cache(object):
 
 
 class LRUCacheNode(object):
-
-    """LRUCache node.
-    """
+    """LRUCache node."""
 
     def __init__(self, key, value):
         self.key = key
@@ -415,7 +404,6 @@ class LRUCacheNode(object):
 
 
 class LRUCache(object):
-
     """Bounded least-recently-used DNS answer cache.
 
     This cache is better than the simple cache (above) if you're
@@ -526,7 +514,6 @@ class LRUCache(object):
 
 
 class Resolver(object):
-
     """DNS stub resolver
 
     @ivar domain: The domain of this host
@@ -1383,9 +1370,9 @@ def override_system_resolver(resolver=None):
     The resolver to use may be specified; if it's not, the default
     resolver will be used.
 
-    @param resolver: the resolver to use
-    @type resolver: dns.resolver.Resolver object or None
+    resolver, a ``dns.resolver.Resolver`` or ``None``, the resolver to use.
     """
+
     if resolver is None:
         resolver = get_default_resolver()
     global _resolver
@@ -1399,8 +1386,8 @@ def override_system_resolver(resolver=None):
 
 
 def restore_system_resolver():
-    """Undo the effects of override_system_resolver().
-    """
+    """Undo the effects of prior override_system_resolver()."""
+
     global _resolver
     _resolver = None
     socket.getaddrinfo = _original_getaddrinfo
diff --git a/doc/exceptions.rst b/doc/exceptions.rst
index 57d1d5f4..fdf0edd1 100644
--- a/doc/exceptions.rst
+++ b/doc/exceptions.rst
@@ -64,6 +64,17 @@ dns.rdataset Exceptions
 .. autoexception:: dns.rdataset.DifferingCovers
 .. autoexception:: dns.rdataset.IncompatibleTypes
 
+dns.resolver Exceptions
+-----------------------
+
+.. autoexception:: dns.resolver.NoAnswer
+.. autoexception:: dns.resolver.NoMetaqueries
+.. autoexception:: dns.resolver.NoNameservers
+.. autoexception:: dns.resolver.NoRootSOA
+.. autoexception:: dns.resolver.NotAbsolute
+.. autoexception:: dns.resolver.NXDOMAIN
+.. autoexception:: dns.resolver.YXDOMAIN
+
 dns.tokenizer Exceptions
 ------------------------
 
diff --git a/doc/resolver-class.rst b/doc/resolver-class.rst
new file mode 100644
index 00000000..3cf2be0d
--- /dev/null
+++ b/doc/resolver-class.rst
@@ -0,0 +1,13 @@
+.. _resolver-class:
+
+The dns.resolver.Resolver Class
+-------------------------------
+
+.. autoclass:: dns.resolver.Resolver
+   :members:
+
+   .. attribute:: domain
+
+      A ``dns.name.Name``, the domain of this host.
+
+   .. more attributes here!      
diff --git a/doc/resolver-override.rst b/doc/resolver-override.rst
new file mode 100644
index 00000000..271013f7
--- /dev/null
+++ b/doc/resolver-override.rst
@@ -0,0 +1,12 @@
+.. _resolver-override:
+
+Overriding the System Resolver
+------------------------------
+
+Sometimes it can be useful to make all of Python use dnspython's resolver
+rather than the default functionality in the ``socket`` module.  Dnspython
+can redefine the entires in the socket module to point at its own code, and
+it can also restore them back to the regular Python defaults.
+
+.. autofunction:: dns.resolver.override_system_resolver
+.. autofunction:: dns.resolver.restore_system_resolver
diff --git a/doc/resolver.rst b/doc/resolver.rst
index 6fad36d8..dc4914e0 100644
--- a/doc/resolver.rst
+++ b/doc/resolver.rst
@@ -6,3 +6,7 @@ Stub Resolver
 
 This is a placeholder.
 
+.. toctree::
+
+   resolver-class
+   resolver-override
-- 
2.47.3