From 5e08c47fb0f95de62d257840fd50055359707d2c Mon Sep 17 00:00:00 2001
From: Bob Halley <halley@dnspython.org>
Date: Sun, 1 Jan 2017 09:28:42 -0800
Subject: [PATCH] doc overhaul for rdatatypes; make CNAME singleton

---
 ChangeLog        |  5 +++
 dns/rdatatype.py | 79 +++++++++++++++++++++++++++---------------------
 2 files changed, 50 insertions(+), 34 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index b62d7882..87d1da98 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2017-01-01  Bob Halley  <halley@dnspython.org>
+
+	* dns/rdatatype.py: CNAME is now a singleton, as the reasons
+	  for permitting multiple CNAMEs are now largely historical.
+
 2016-11-15  Bob Halley  <halley@dnspython.org>
 
 	* Fixed regression where trailing zeros in APL RRs were not
diff --git a/dns/rdatatype.py b/dns/rdatatype.py
index 33a7461b..48d2aa67 100644
--- a/dns/rdatatype.py
+++ b/dns/rdatatype.py
@@ -1,4 +1,4 @@
-# Copyright (C) 2001-2007, 2009-2011 Nominum, Inc.
+# Copyright (C) 2001-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,
@@ -13,18 +13,7 @@
 # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
 # OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-"""DNS Rdata Types.
-
-@var _by_text: The rdata type textual name to value mapping
-@type _by_text: dict
-@var _by_value: The rdata type value to textual name mapping
-@type _by_value: dict
-@var _metatypes: If an rdatatype is a metatype, there will be a mapping
-whose key is the rdatatype value and whose value is True in this dictionary.
-@type _metatypes: dict
-@var _singletons: If an rdatatype is a singleton, there will be a mapping
-whose key is the rdatatype value and whose value is True in this dictionary.
-@type _singletons: dict"""
+"""DNS Rdata Types."""
 
 import re
 
@@ -180,7 +169,6 @@ _by_text = {
 
 _by_value = dict((y, x) for x, y in _by_text.items())
 
-
 _metatypes = {
     OPT: True
 }
@@ -190,24 +178,30 @@ _singletons = {
     NXT: True,
     DNAME: True,
     NSEC: True,
-    # CNAME is technically a singleton, but we allow multiple CNAMEs.
+    CNAME: True,
 }
 
 _unknown_type_pattern = re.compile('TYPE([0-9]+)$', re.I)
 
 
 class UnknownRdatatype(dns.exception.DNSException):
-
     """DNS resource record type is unknown."""
 
 
 def from_text(text):
     """Convert text into a DNS rdata type value.
-    @param text: the text
-    @type text: string
-    @raises dns.rdatatype.UnknownRdatatype: the type is unknown
-    @raises ValueError: the rdata type value is not >= 0 and <= 65535
-    @rtype: int"""
+
+    The input text can be a defined DNS RR type mnemonic or
+    instance of the DNS generic type syntax.
+
+    For example, "NS" and "TYPE2" will both result in a value of 2.
+
+    Raises ``dns.rdatatype.UnknownRdatatype`` if the type is unknown.
+
+    Raises ``ValueError`` if the rdata type value is not >= 0 and <= 65535.
+
+    Returns an ``int``.
+    """
 
     value = _by_text.get(text.upper())
     if value is None:
@@ -221,11 +215,15 @@ def from_text(text):
 
 
 def to_text(value):
-    """Convert a DNS rdata type to text.
-    @param value: the rdata type value
-    @type value: int
-    @raises ValueError: the rdata type value is not >= 0 and <= 65535
-    @rtype: string"""
+    """Convert a DNS rdata type value to text.
+
+    If the value has a known mnemonic, it will be used, otherwise the
+    DNS generic type syntax will be used.
+
+    Raises ``ValueError`` if the rdata type value is not >= 0 and <= 65535.
+
+    Returns a ``str``.
+    """
 
     if value < 0 or value > 65535:
         raise ValueError("type must be between >= 0 and <= 65535")
@@ -236,10 +234,15 @@ def to_text(value):
 
 
 def is_metatype(rdtype):
-    """True if the type is a metatype.
-    @param rdtype: the type
-    @type rdtype: int
-    @rtype: bool"""
+    """True if the specified type is a metatype.
+
+    *rdtype* is an ``int``.
+
+    The currently defined metatypes are TKEY, TSIG, IXFR, AXFR, MAILA,
+    MAILB, ANY, and OPT.
+
+    Returns a ``bool``.
+    """
 
     if rdtype >= TKEY and rdtype <= ANY or rdtype in _metatypes:
         return True
@@ -247,10 +250,18 @@ def is_metatype(rdtype):
 
 
 def is_singleton(rdtype):
-    """True if the type is a singleton.
-    @param rdtype: the type
-    @type rdtype: int
-    @rtype: bool"""
+    """Is the specified type a singleton type?
+
+    Singleton types can only have a single rdata in an rdataset, or a single
+    RR in an RRset.
+
+    The currently defined singleton types are CNAME, DNAME, NSEC, NXT, and
+    SOA.
+
+    *rdtype* is an ``int``.
+
+    Returns a ``bool``.
+    """
 
     if rdtype in _singletons:
         return True
-- 
2.47.3