From 76e284a9695e996d0fad7757e25c4e687fefbc7d Mon Sep 17 00:00:00 2001
From: Bob Halley <halley@dnspython.org>
Date: Tue, 3 Jan 2017 15:29:55 -0800
Subject: [PATCH] more doco updates

---
 dns/ipv4.py       | 20 +++++++++++---------
 dns/ipv6.py       | 28 +++++++++++++++++-----------
 doc/manual.rst    |  1 +
 doc/utilities.rst | 13 +++++++++++++
 4 files changed, 42 insertions(+), 20 deletions(-)
 create mode 100644 doc/utilities.rst

diff --git a/dns/ipv4.py b/dns/ipv4.py
index b9ce00d4..a67a84b6 100644
--- 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 9ced9bf7..fcc0d930 100644
--- 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 b3e18b07..f44b39bb 100644
--- 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
index 00000000..1f5475d1
--- /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:
-- 
2.47.3