doc overhaul

diff --git a/dns/rdataclass.py b/dns/rdataclass.py
index 17a4810d524bb7c2be8e662d65f00553737653a9..916dc615c4b2a116cc105802bda7bd9fa732a3da 100644 (file)
--- a/dns/rdataclass.py
+++ b/dns/rdataclass.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,15 +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 Classes.
-
-@var _by_text: The rdata class textual name to value mapping
-@type _by_text: dict
-@var _by_value: The rdata class value to textual name mapping
-@type _by_value: dict
-@var _metaclasses: If an rdataclass is a metaclass, there will be a mapping
-whose key is the rdatatype value and whose value is True in this dictionary.
-@type _metaclasses: dict"""
+"""DNS Rdata Classes."""
 
 import re
 
@@ -67,17 +59,22 @@ _unknown_class_pattern = re.compile('CLASS([0-9]+)$', re.I)
 
 
 class UnknownRdataclass(dns.exception.DNSException):
-
     """A DNS class is unknown."""
 
 
 def from_text(text):
     """Convert text into a DNS rdata class value.
-    @param text: the text
-    @type text: string
-    @rtype: int
-    @raises dns.rdataclass.UnknownRdataclass: the class is unknown
-    @raises ValueError: the rdata class value is not >= 0 and <= 65535
+
+    The input text can be a defined DNS RR class mnemonic or
+    instance of the DNS generic class syntax.
+
+    For example, "IN" and "CLASS1" will both result in a value of 1.
+
+    Raises ``dns.rdatatype.UnknownRdataclass`` if the class is unknown.
+
+    Raises ``ValueError`` if the rdata class value is not >= 0 and <= 65535.
+
+    Returns an ``int``.
     """
 
     value = _by_text.get(text.upper())
@@ -92,11 +89,14 @@ def from_text(text):
 
 
 def to_text(value):
-    """Convert a DNS rdata class to text.
-    @param value: the rdata class value
-    @type value: int
-    @rtype: string
-    @raises ValueError: the rdata class value is not >= 0 and <= 65535
+    """Convert a DNS rdata type value to text.
+
+    If the value has a known mnemonic, it will be used, otherwise the
+    DNS generic class syntax will be used.
+
+    Raises ``ValueError`` if the rdata class value is not >= 0 and <= 65535.
+
+    Returns a ``str``.
     """
 
     if value < 0 or value > 65535:
@@ -108,10 +108,12 @@ def to_text(value):
 
 
 def is_metaclass(rdclass):
-    """True if the class is a metaclass.
-    @param rdclass: the rdata class
-    @type rdclass: int
-    @rtype: bool"""
+    """True if the specified class is a metaclass.
+
+    The currently defined metaclasses are ANY and NONE.
+
+    *rdclass* is an ``int``.
+    """
 
     if rdclass in _metaclasses:
         return True