oh no, more docs!

git-svn-id: svn://bind10.isc.org/svn/bind10/experiments/python-binding@2084 e5f2f494-b856-4b98-b285-d166d9295462

src/lib/dns/python/libdns_python.cc

@@ -43,7 +43,11 @@
 static PyModuleDef libdns_python = {
     { PyObject_HEAD_INIT(NULL) NULL, 0, NULL},
     "libdns_python",
-    "Python bindings for isc.dns",
+    "Python bindings for the classes in the isc::dns namespace.\n\n"
+    "These bindings match the original C++ API as closely as possible, "
+    "but are not complete. Some classes are unnecessary (InputBuffer "
+    "and OutputBuffer for instance), and others may be necessary, but "
+    "were not up to now.",
     -1,
     NULL,
     NULL,

src/lib/dns/python/question_python.cc

@@ -67,11 +67,21 @@ static PyObject* Question_toWire(s_Question* self, PyObject* args);
 // 3. Argument type
 // 4. Documentation
 static PyMethodDef Question_methods[] = {
-    { "get_name", (PyCFunction)Question_getName, METH_NOARGS, "Return the name" },
-    { "get_type", (PyCFunction)Question_getType, METH_NOARGS, "Return the rr type" },
-    { "get_class", (PyCFunction)Question_getClass, METH_NOARGS, "Return the rr class" },
-    { "to_text", (PyCFunction)Question_toText, METH_NOARGS, "Return the string representation" },
-    { "to_wire", (PyCFunction)Question_toWire, METH_VARARGS, "to wire format" },
+    { "get_name", (PyCFunction)Question_getName, METH_NOARGS,
+      "Returns the Name" },
+    { "get_type", (PyCFunction)Question_getType, METH_NOARGS,
+      "Returns the RRType" },
+    { "get_class", (PyCFunction)Question_getClass, METH_NOARGS,
+      "Returns the RRClass" },
+    { "to_text", (PyCFunction)Question_toText, METH_NOARGS,
+      "Returns the string representation" },
+    { "to_wire", (PyCFunction)Question_toWire, METH_VARARGS,
+      "Converts the Question object to wire format.\n"
+      "The argument can be either a MessageRenderer or an object that "
+      "implements the sequence interface. If the object is mutable "
+      "(for instance a bytearray()), the wire data is added in-place.\n"
+      "If it is not (for instance a bytes() object), a new object is "
+      "returned" },
     { NULL, NULL, 0, NULL }
 };
 
@@ -99,7 +109,8 @@ static PyTypeObject question_type = {
     NULL,                               /* tp_setattro */
     NULL,                               /* tp_as_buffer */
     Py_TPFLAGS_DEFAULT,                 /* tp_flags */
-    "C++ Question Object",               /* tp_doc */
+    "The Question class encapsulates the common search key of DNS"
+    "lookup, consisting of owner name, RR type and RR class.",
     NULL,                               /* tp_traverse */
     NULL,                               /* tp_clear */
     NULL,                               /* tp_richcompare */

src/lib/dns/python/rdata_python.cc

@@ -68,8 +68,15 @@ static PyObject* Rdata_toWire(s_Rdata* self, PyObject* args);
 // 3. Argument type
 // 4. Documentation
 static PyMethodDef Rdata_methods[] = {
-    { "to_text", (PyCFunction)Rdata_toText, METH_NOARGS, "Return the string representation" },
-    { "to_wire", (PyCFunction)Rdata_toWire, METH_VARARGS, "wire format" },
+    { "to_text", (PyCFunction)Rdata_toText, METH_NOARGS,
+      "Returns the string representation" },
+    { "to_wire", (PyCFunction)Rdata_toWire, METH_VARARGS,
+      "Converts the Rdata object to wire format.\n"
+      "The argument can be either a MessageRenderer or an object that "
+      "implements the sequence interface. If the object is mutable "
+      "(for instance a bytearray()), the wire data is added in-place.\n"
+      "If it is not (for instance a bytes() object), a new object is "
+      "returned" },
     { NULL, NULL, 0, NULL }
 };
 
@@ -97,7 +104,8 @@ static PyTypeObject rdata_type = {
     NULL,                               /* tp_setattro */
     NULL,                               /* tp_as_buffer */
     Py_TPFLAGS_DEFAULT,                 /* tp_flags */
-    "C++ Rdata Object",                 /* tp_doc */
+    "The Rdata class is an abstract base class that provides "
+    "a set of common interfaces to manipulate concrete RDATA objects.",
     NULL,                               /* tp_traverse */
     NULL,                               /* tp_clear */
     NULL,                               /* tp_richcompare */
@@ -218,13 +226,13 @@ initModulePart_Rdata(PyObject* mod)
 
     // Add the exceptions to the class
     po_InvalidRdataLength = PyErr_NewException("libdns_python.InvalidRdataLength", NULL, NULL);
-    addClassVariable(rdata_type, "InvalidRdataLength", po_InvalidRdataLength);
+    PyModule_AddObject(mod, "InvalidRdataLength", po_InvalidRdataLength);
 
     po_InvalidRdataText = PyErr_NewException("libdns_python.InvalidRdataText", NULL, NULL);
-    addClassVariable(rdata_type, "InvalidRdataText", po_InvalidRdataText);
+    PyModule_AddObject(mod, "InvalidRdataText", po_InvalidRdataText);
 
     po_CharStringTooLong = PyErr_NewException("libdns_python.CharStringTooLong", NULL, NULL);
-    addClassVariable(rdata_type, "CharStringTooLong", po_CharStringTooLong);
+    PyModule_AddObject(mod, "CharStringTooLong", po_CharStringTooLong);
 
     
     return true;

src/lib/dns/python/rrclass_python.cc

@@ -68,9 +68,17 @@ static PyObject* RRClass_richcmp(s_RRClass* self, s_RRClass* other, int op);
 // 3. Argument type
 // 4. Documentation
 static PyMethodDef RRClass_methods[] = {
-    { "to_text", (PyCFunction)RRClass_toText, METH_NOARGS, "Return the string representation" },
-    { "to_wire", (PyCFunction)RRClass_toWire, METH_VARARGS, "to wire format" },
-    { "get_code", (PyCFunction)RRClass_getCode, METH_NOARGS, "Return the class code as an integer" },
+    { "to_text", (PyCFunction)RRClass_toText, METH_NOARGS,
+      "Returns the string representation" },
+    { "to_wire", (PyCFunction)RRClass_toWire, METH_VARARGS,
+      "Converts the RRClass object to wire format.\n"
+      "The argument can be either a MessageRenderer or an object that "
+      "implements the sequence interface. If the object is mutable "
+      "(for instance a bytearray()), the wire data is added in-place.\n"
+      "If it is not (for instance a bytes() object), a new object is "
+      "returned" },
+    { "get_code", (PyCFunction)RRClass_getCode, METH_NOARGS,
+      "Returns the class code as an integer" },
     { NULL, NULL, 0, NULL }
 };
 
@@ -98,7 +106,10 @@ static PyTypeObject rrclass_type = {
     NULL,                               /* tp_setattro */
     NULL,                               /* tp_as_buffer */
     Py_TPFLAGS_DEFAULT,                 /* tp_flags */
-    "C++ RRClass Object",               /* tp_doc */
+    "The RRClass class encapsulates DNS resource record classes.\n"
+    "This class manages the 16-bit integer class codes in quite a straightforward"
+    "way.  The only non trivial task is to handle textual representations of"
+    "RR classes, such as \"IN\", \"CH\", or \"CLASS65534\".",
     NULL,                               /* tp_traverse */
     NULL,                               /* tp_clear */
     (richcmpfunc)RRClass_richcmp,       /* tp_richcompare */

src/lib/dns/python/rrset_python.cc

@@ -71,17 +71,33 @@ static PyObject* RRset_getRdata(s_RRset* self);
 // TODO: iterator?
 
 static PyMethodDef RRset_methods[] = {
-    { "get_rdata_count", (PyCFunction)RRset_getRdataCount, METH_NOARGS, "Return the number of rdata fields" },
-    { "get_name", (PyCFunction)RRset_getName, METH_NOARGS, "Return" },
-    { "get_class", (PyCFunction)RRset_getClass, METH_NOARGS, "Return" },
-    { "get_type", (PyCFunction)RRset_getType, METH_NOARGS, "Return" },
-    { "get_ttl", (PyCFunction)RRset_getTTL, METH_NOARGS, "Return" },
-    { "set_name", (PyCFunction)RRset_setName, METH_VARARGS, "Return" },
-    { "set_ttl", (PyCFunction)RRset_setTTL, METH_VARARGS, "Return" },
-    { "to_text", (PyCFunction)RRset_toText, METH_NOARGS, "Return" },
-    { "to_wire", (PyCFunction)RRset_toWire, METH_VARARGS, "Return" },
-    { "add_rdata", (PyCFunction)RRset_addRdata, METH_VARARGS, "Return" },
-    { "get_rdata", (PyCFunction)RRset_getRdata, METH_NOARGS, "Returns a List containing all Rdata elements" },
+    { "get_rdata_count", (PyCFunction)RRset_getRdataCount, METH_NOARGS,
+      "Returns the number of rdata fields." },
+    { "get_name", (PyCFunction)RRset_getName, METH_NOARGS,
+      "Returns the name of the RRset, as a Name object." },
+    { "get_class", (PyCFunction)RRset_getClass, METH_NOARGS,
+      "Returns the class of the RRset as an RRClass object." },
+    { "get_type", (PyCFunction)RRset_getType, METH_NOARGS,
+      "Returns the type of the RRset as an RRType object." },
+    { "get_ttl", (PyCFunction)RRset_getTTL, METH_NOARGS,
+      "Returns the TTL of the RRset as an RRTTL object." },
+    { "set_name", (PyCFunction)RRset_setName, METH_VARARGS,
+      "Sets the name of the RRset.\nTakes a Name object as an argument." },
+    { "set_ttl", (PyCFunction)RRset_setTTL, METH_VARARGS,
+      "Sets the TTL of the RRset.\nTakes an RRTTL object as an argument." },
+    { "to_text", (PyCFunction)RRset_toText, METH_NOARGS,
+      "Returns the text representation of the RRset as a string" },
+    { "to_wire", (PyCFunction)RRset_toWire, METH_VARARGS,
+      "Converts the RRset object to wire format.\n"
+      "The argument can be either a MessageRenderer or an object that "
+      "implements the sequence interface. If the object is mutable "
+      "(for instance a bytearray()), the wire data is added in-place.\n"
+      "If it is not (for instance a bytes() object), a new object is "
+      "returned" },
+    { "add_rdata", (PyCFunction)RRset_addRdata, METH_VARARGS,
+      "Adds the rdata for one RR to the RRset.\nTakes an Rdata object as an argument" },
+    { "get_rdata", (PyCFunction)RRset_getRdata, METH_NOARGS,
+      "Returns a List containing all Rdata elements" },
     { NULL, NULL, 0, NULL }
 };
 
@@ -106,7 +122,22 @@ static PyTypeObject rrset_type = {
     NULL,                               /* tp_setattro */
     NULL,                               /* tp_as_buffer */
     Py_TPFLAGS_DEFAULT,                 /* tp_flags */
-    "C++ Name Object",  /* tp_doc */
+    "The AbstractRRset class is an abstract base class that "
+    "models a DNS RRset.\n\n"
+    "An object of (a specific derived class of) AbstractRRset "
+    "models an RRset as described in the DNS standard:\n"
+    "A set of DNS resource records (RRs) of the same type and class. "
+    "The standard requires the TTL of all RRs in an RRset be the same; "
+    "this class follows that requirement.\n\n"
+    "Note about duplicate RDATA: RFC2181 states that it's meaningless that an "
+    "RRset contains two identical RRs and that name servers should suppress "
+    "such duplicates.\n"
+    "This class is not responsible for ensuring this requirement: For example, "
+    "addRdata() method doesn't check if there's already RDATA identical "
+    "to the one being added.\n"
+    "This is because such checks can be expensive, and it's often easy to "
+    "ensure the uniqueness requirement at the %data preparation phase "
+    "(e.g. when loading a zone).",
     NULL,                               /* tp_traverse */
     NULL,                               /* tp_clear */
     NULL,                               /* tp_richcompare */
@@ -366,7 +397,6 @@ initModulePart_RRset(PyObject* mod)
 {
     // Add the exceptions to the module
     po_EmptyRRset = PyErr_NewException("libdns_python.EmptyRRset", NULL, NULL);
-    Py_INCREF(po_EmptyRRset);
     PyModule_AddObject(mod, "EmptyRRset", po_EmptyRRset);
 
     // Add the enums to the module

src/lib/dns/python/rrttl_python.cc

@@ -68,9 +68,17 @@ static PyObject* RRTTL_richcmp(s_RRTTL* self, s_RRTTL* other, int op);
 // 3. Argument type
 // 4. Documentation
 static PyMethodDef RRTTL_methods[] = {
-    { "to_text", (PyCFunction)RRTTL_toText, METH_NOARGS, "Return the string representation" },
-    { "to_wire", (PyCFunction)RRTTL_toWire, METH_VARARGS, "to wire format" },
-    { "get_value", (PyCFunction)RRTTL_getValue, METH_NOARGS, "Return the TTL as an integer" },
+    { "to_text", (PyCFunction)RRTTL_toText, METH_NOARGS,
+      "Returns the string representation" },
+    { "to_wire", (PyCFunction)RRTTL_toWire, METH_VARARGS,
+      "Converts the RRTTL object to wire format.\n"
+      "The argument can be either a MessageRenderer or an object that "
+      "implements the sequence interface. If the object is mutable "
+      "(for instance a bytearray()), the wire data is added in-place.\n"
+      "If it is not (for instance a bytes() object), a new object is "
+      "returned" },
+    { "get_value", (PyCFunction)RRTTL_getValue, METH_NOARGS,
+      "Returns the TTL as an integer" },
     { NULL, NULL, 0, NULL }
 };
 
@@ -98,7 +106,12 @@ static PyTypeObject rrttl_type = {
     NULL,                               /* tp_setattro */
     NULL,                               /* tp_as_buffer */
     Py_TPFLAGS_DEFAULT,                 /* tp_flags */
-    "C++ RRTTL Object",               /* tp_doc */
+    "The RRTTL class encapsulates TTLs used in DNS resource records.\n\n"
+    "This is a straightforward class; an RRTTL object simply maintains a "
+    "32-bit unsigned integer corresponding to the TTL value.  The main purpose "
+    "of this class is to provide convenient interfaces to convert a textual "
+    "representation into the integer TTL value and vice versa, and to handle "
+    "wire-format representations.",
     NULL,                               /* tp_traverse */
     NULL,                               /* tp_clear */
     (richcmpfunc)RRTTL_richcmp,       /* tp_richcompare */
@@ -282,10 +295,8 @@ initModulePart_RRTTL(PyObject* mod)
 {
     // Add the exceptions to the module
     po_InvalidRRTTL = PyErr_NewException("libdns_python.InvalidRRTTL", NULL, NULL);
-    Py_INCREF(po_InvalidRRTTL);
     PyModule_AddObject(mod, "InvalidRRTTL", po_InvalidRRTTL);
     po_IncompleteRRTTL = PyErr_NewException("libdns_python.IncompleteRRTTL", NULL, NULL);
-    Py_INCREF(po_IncompleteRRTTL);
     PyModule_AddObject(mod, "IncompleteRRTTL", po_IncompleteRRTTL);
 
     // We initialize the static description object with PyType_Ready(),

src/lib/dns/python/rrtype_python.cc

@@ -69,9 +69,17 @@ static PyObject* RRType_richcmp(s_RRType* self, s_RRType* other, int op);
 // 3. Argument type
 // 4. Documentation
 static PyMethodDef RRType_methods[] = {
-    { "to_text", (PyCFunction)RRType_toText, METH_NOARGS, "Return the string representation" },
-    { "to_wire", (PyCFunction)RRType_toWire, METH_VARARGS, "to wire format" },
-    { "get_code", (PyCFunction)RRType_getCode, METH_NOARGS, "Return the class code as an integer" },
+    { "to_text", (PyCFunction)RRType_toText, METH_NOARGS,
+      "Returns the string representation" },
+    { "to_wire", (PyCFunction)RRType_toWire, METH_VARARGS,
+      "Converts the RRType object to wire format.\n"
+      "The argument can be either a MessageRenderer or an object that "
+      "implements the sequence interface. If the object is mutable "
+      "(for instance a bytearray()), the wire data is added in-place.\n"
+      "If it is not (for instance a bytes() object), a new object is "
+      "returned" },
+    { "get_code", (PyCFunction)RRType_getCode, METH_NOARGS,
+      "Returns the type code as an integer" },
     { NULL, NULL, 0, NULL }
 };
 
@@ -99,7 +107,10 @@ static PyTypeObject rrtype_type = {
     NULL,                               /* tp_setattro */
     NULL,                               /* tp_as_buffer */
     Py_TPFLAGS_DEFAULT,                 /* tp_flags */
-    "C++ RRType Object",               /* tp_doc */
+    "The RRType class encapsulates DNS resource record types.\n\n"
+    "This class manages the 16-bit integer type codes in quite a straightforward "
+    "way. The only non trivial task is to handle textual representations of "
+    "RR types, such as \"A\", \"AAAA\", or \"TYPE65534\".",
     NULL,                               /* tp_traverse */
     NULL,                               /* tp_clear */
     (richcmpfunc)RRType_richcmp,       /* tp_richcompare */
@@ -287,10 +298,8 @@ initModulePart_RRType(PyObject* mod)
 {
     // Add the exceptions to the module
     po_InvalidRRType = PyErr_NewException("libdns_python.InvalidRRType", NULL, NULL);
-    Py_INCREF(po_InvalidRRType);
     PyModule_AddObject(mod, "InvalidRRType", po_InvalidRRType);
     po_IncompleteRRType = PyErr_NewException("libdns_python.IncompleteRRType", NULL, NULL);
-    Py_INCREF(po_IncompleteRRType);
     PyModule_AddObject(mod, "IncompleteRRType", po_IncompleteRRType);
 
     // We initialize the static description object with PyType_Ready(),