From 8cd2dadb45fbe08b9e0cf58e323f0e5b4a134e9f Mon Sep 17 00:00:00 2001
From: Bob Halley <halley@dnspython.org>
Date: Sun, 15 Jan 2017 16:02:00 -0800
Subject: [PATCH] namedict doco

---
 dns/namedict.py   | 25 +++++++++++++------------
 doc/name-dict.rst |  7 +++++++
 doc/name.rst      |  1 +
 3 files changed, 21 insertions(+), 12 deletions(-)
 create mode 100644 doc/name-dict.rst

diff --git a/dns/namedict.py b/dns/namedict.py
index 58e40344..2215af71 100644
--- a/dns/namedict.py
+++ b/dns/namedict.py
@@ -1,4 +1,4 @@
-# Copyright (C) 2003-2007, 2009-2011 Nominum, Inc.
+# Copyright (C) 2003-2017 Nominum, Inc.
 # Copyright (C) 2016 Coresec Systems AB
 #
 # Permission to use, copy, modify, and distribute this software and its
@@ -31,20 +31,19 @@ from ._compat import xrange
 
 
 class NameDict(collections.MutableMapping):
-
     """A dictionary whose keys are dns.name.Name objects.
-    @ivar max_depth: the maximum depth of the keys that have ever been
-    added to the dictionary.
-    @type max_depth: int
-    @ivar max_depth_items: the number of items of maximum depth
-    @type max_depth_items: int
+
+    In addition to being like a regular Python dictionary, this
+    dictionary can also get the deepest match for a given key.
     """
 
     __slots__ = ["max_depth", "max_depth_items", "__store"]
 
     def __init__(self, *args, **kwargs):
         self.__store = dict()
+        #: the maximum depth of the keys that have ever been added
         self.max_depth = 0
+        #: the number of items of maximum depth
         self.max_depth_items = 0
         self.update(dict(*args, **kwargs))
 
@@ -83,14 +82,16 @@ class NameDict(collections.MutableMapping):
         return key in self.__store
 
     def get_deepest_match(self, name):
-        """Find the deepest match to I{name} in the dictionary.
+        """Find the deepest match to *fname* in the dictionary.
 
         The deepest match is the longest name in the dictionary which is
-        a superdomain of I{name}.
+        a superdomain of *name*.  Note that *superdomain* includes matching
+        *name* itself.
+
+        *name*, a ``dns.name.Name``, the name to find.
 
-        @param name: the name
-        @type name: dns.name.Name object
-        @rtype: (key, value) tuple
+        Returns a ``(key, value)`` where *key* is the deepest
+        ``dns.name.Name``, and *value* is the value associated with *key*.
         """
 
         depth = len(name)
diff --git a/doc/name-dict.rst b/doc/name-dict.rst
new file mode 100644
index 00000000..da9a8464
--- /dev/null
+++ b/doc/name-dict.rst
@@ -0,0 +1,7 @@
+.. _name-dict:
+
+Name Dictionary
+===============
+
+.. autoclass:: dns.namedict.NameDict
+   :members:
diff --git a/doc/name.rst b/doc/name.rst
index 201e69b5..b1229a50 100644
--- a/doc/name.rst
+++ b/doc/name.rst
@@ -38,5 +38,6 @@ full details.
 
    name-class
    name-make
+   name-dict
    name-helpers
    name-codecs
-- 
2.47.3