more doco updates

diff --git a/dns/ipv4.py b/dns/ipv4.py
index b9ce00d410bbf6460593131465bbc6659688e03b..a67a84b60a9f77ef85e9d05edd2af506a0bc7058 100644 (file)
--- a/dns/ipv4.py
+++ b/dns/ipv4.py
@@ -1,4 +1,4 @@
-# Copyright (C) 2003-2007, 2009-2011 Nominum, Inc.
+# Copyright (C) 2003-2017 Nominum, Inc.
 #
 # Permission to use, copy, modify, and distribute this software and its
 # documentation for any purpose with or without fee is hereby granted,
@@ -21,12 +21,13 @@ import dns.exception
 from ._compat import binary_type
 
 def inet_ntoa(address):
-    """Convert an IPv4 address in network form to text form.
+    """Convert an IPv4 address in binary form to text form.
 
-    @param address: The IPv4 address
-    @type address: string
-    @returns: string
+    *address*, a ``binary``, the IPv4 address in binary form.
+
+    Returns a ``text``.
     """
+
     if len(address) != 4:
         raise dns.exception.SyntaxError
     if not isinstance(address, bytearray):
@@ -35,12 +36,13 @@ def inet_ntoa(address):
                              address[2], address[3]))
 
 def inet_aton(text):
-    """Convert an IPv4 address in text form to network form.
+    """Convert an IPv4 address in text form to binary form.
 
-    @param text: The IPv4 address
-    @type text: string
-    @returns: string
+    *text*, a ``text``, the IPv4 address in textual form.
+
+    Returns a ``binary``.
     """
+
     if not isinstance(text, binary_type):
         text = text.encode()
     parts = text.split(b'.')

diff --git a/dns/ipv6.py b/dns/ipv6.py
index 9ced9bf7a02f463103549e17dbf6aa086d945bc5..fcc0d93001a5a4c50232a43b5ed72c5bc71d89aa 100644 (file)
--- a/dns/ipv6.py
+++ b/dns/ipv6.py
@@ -1,4 +1,4 @@
-# Copyright (C) 2003-2007, 2009-2011 Nominum, Inc.
+# Copyright (C) 2003-2017 Nominum, Inc.
 #
 # Permission to use, copy, modify, and distribute this software and its
 # documentation for any purpose with or without fee is hereby granted,
@@ -25,12 +25,12 @@ from ._compat import xrange, binary_type, maybe_decode
 _leading_zero = re.compile('0+([0-9a-f]+)')
 
 def inet_ntoa(address):
-    """Convert a network format IPv6 address into text.
+    """Convert an IPv6 address in binary form to text form.
 
-    @param address: the binary address
-    @type address: string
-    @rtype: string
-    @raises ValueError: the address isn't 16 bytes long
+    *address*, a ``binary``, the IPv6 address in binary form.
+
+    Raises ``ValueError`` if the address isn't 16 bytes long.
+    Returns a ``text``.
     """
 
     if len(address) != 16:
@@ -96,12 +96,11 @@ _colon_colon_start = re.compile(b'::.*')
 _colon_colon_end = re.compile(b'.*::$')
 
 def inet_aton(text):
-    """Convert a text format IPv6 address into network format.
+    """Convert an IPv6 address in text form to binary form.
+
+    *text*, a ``text``, the IPv6 address in textual form.
 
-    @param text: the textual address
-    @type text: string
-    @rtype: string
-    @raises dns.exception.SyntaxError: the text was not properly formatted
+    Returns a ``binary``.
     """
 
     #
@@ -169,4 +168,11 @@ def inet_aton(text):
 _mapped_prefix = b'\x00' * 10 + b'\xff\xff'
 
 def is_mapped(address):
+    """Is the specified address a mapped IPv4 address?
+
+    *address*, a ``binary`` is an IPv6 address in binary form.
+
+    Returns a ``bool``.
+    """
+
     return address.startswith(_mapped_prefix)

diff --git a/doc/manual.rst b/doc/manual.rst
index b3e18b076410a564199cfe0cdc961238c969c2f7..f44b39bbab65841b4ec64be976ac77d8c561d882 100644 (file)
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -9,3 +9,4 @@ Dnspython Manual
    name
    rdata
    exceptions
+   utilities

diff --git a/doc/utilities.rst b/doc/utilities.rst
new file mode 100644 (file)
index 0000000..1f5475d
--- /dev/null
+++ b/doc/utilities.rst
@@ -0,0 +1,13 @@
+.. _utilities:
+
+Miscellaneous Utilities
+-----------------------
+
+.. automodule:: dns.inet
+   :members:
+
+.. automodule:: dns.ipv4
+   :members:
+
+.. automodule:: dns.ipv6
+   :members: