namedict doco

diff --git a/dns/namedict.py b/dns/namedict.py
index 58e403440a6fd2e8e21cf890025a0e4282b2bf6d..2215af71b0c3627abfb86e6a22e1d84293232fe1 100644 (file)
--- 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 (file)
index 0000000..da9a846
--- /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 201e69b54567e64ad310dc7bf228139fdd46b41b..b1229a509b5b0f5c4d2cce2802f98f0037626e89 100644 (file)
--- a/doc/name.rst
+++ b/doc/name.rst
@@ -38,5 +38,6 @@ full details.
 
    name-class
    name-make
+   name-dict
    name-helpers
    name-codecs