[trac983] overall documentation updates. more cleanup.

src/lib/python/isc/acl/Makefile.am

@@ -28,3 +28,5 @@ acl_la_LIBADD += $(PYTHON_LIB)
 dns_la_LDFLAGS += -module
 dns_la_LIBADD = $(top_builddir)/src/lib/acl/libdnsacl.la
 dns_la_LIBADD += $(PYTHON_LIB)
+
+EXTRA_DIST = dnsacl_inc.cc dns_requestacl_inc.cc dns_requestcontext_inc.cc

src/lib/python/isc/acl/dns.cc

@@ -35,6 +35,8 @@ using namespace isc::data;
 using namespace isc::acl::dns;
 using namespace isc::acl::dns::python;
 
+#include "dnsacl_inc.cc"
+
 namespace {
 PyObject*
 loadRequestACL(PyObject*, PyObject* args) {
@@ -63,7 +65,7 @@ loadRequestACL(PyObject*, PyObject* args) {
 }
 
 PyMethodDef methods[] = {
-    { "load_request_acl", loadRequestACL, METH_VARARGS, "TBD" },
+    { "load_request_acl", loadRequestACL, METH_VARARGS, load_request_acl_doc },
     { NULL, NULL, 0, NULL }
 };
 

src/lib/python/isc/acl/dns_requestacl_inc.cc

@@ -1,43 +1,24 @@
 namespace {
 const char* const RequestACL_doc = "\
-The ACL itself.\n\
+The DNS Request ACL.\n\
 \n\
-It holds bunch of ordered entries, each one consisting of a check ( of\n\
-any kind, it might be even compound) and an action that is returned\n\
-whenever the action matches. They are tested in the order and first\n\
-match counts.\n\
+It holds bunch of ordered entries, each one consisting of a check for\n\
+a given DNS Request context and an action, which is one of ACCEPT,\n\
+REJECT, or DROP, as defined in the isc.acl module.\n\
+The checks are tested in the order and first match counts.\n\
 \n\
-This is non-copyable. It seems that there's no need to copy them (even\n\
-when it would be technically possible), so we forbid it just to\n\
-prevent copying it by accident. If there really is legitimate use,\n\
-this restriction can be removed.\n\
-\n\
-The class is template. It is possible to specify on which context the\n\
-checks match and which actions it returns. The actions must be\n\
-copyable for this to work and it is expected to be something small,\n\
-usually an enum (but other objects are also possible).\n\
-\n\
-There are protected functions. In fact, you should consider them\n\
-private, they are protected so tests can get inside. This class is not\n\
-expected to be subclassed in real applications.\n\
-\n\
-ACL(default_action)\n\
-\n\
-    Constructor.\n\
-\n\
-    Parameters:\n\
-      default_action It is the action that is returned when the\n\
-                 checked things \"falls off\" the end of the list\n\
-                 (when no rule matched).\n\
+A RequestACL object cannot be constructed directly; an application\n\
+must use isc.acl.dns.load_request_acl() to create a RequestACL object.\n\
 \n\
 ";
 
 const char* const RequestACL_execute_doc = "\
-execute(context) ->  Action \n\
+execute(context) -> action \n\
 \n\
-The actual main function that decides.\n\
+The returned action is one of ACCEPT, REJECT or DROP as defined in\n\
+the isc.acl module.\n\
 \n\
-This is the function that takes the entries one by one, checks the\n\
+This is the function that takes the ACL entries one by one, checks the\n\
 context against conditions and if it matches, returns the action that\n\
 belongs to the first matched entry or default action if nothing\n\
 matches.\n\

src/lib/python/isc/acl/dns_requestacl_python.cc

@@ -163,7 +163,6 @@ PyTypeObject requestacl_type = {
     0                                   // tp_version_tag
 };
 
-// Module Initialization, all statics are initialized here
 bool
 initModulePart_RequestACL(PyObject* mod) {
     // We initialize the static description object with PyType_Ready(),

src/lib/python/isc/acl/dns_requestcontext_inc.cc

@@ -0,0 +1,30 @@
+namespace {
+const char* const RequestContext_doc = "\
+DNS request to be checked.\n\
+\n\
+This plays the role of ACL context for the RequestACL object.\n\
+\n\
+Based on the minimalist philosophy, the initial implementation only\n\
+maintains the remote (source) IP address of the request. The plan is\n\
+to add more parameters of the request. A scheduled next step is to\n\
+support the TSIG key (if it's included in the request). Other\n\
+possibilities are the local (destination) IP address, the remote and\n\
+local port numbers, various fields of the DNS request (e.g. a\n\
+particular header flag value).\n\
+\n\
+RequestContext(remote_address)\n\
+\n\
+    In this initial implementation, the constructor only takes a\n\
+    remote IP address in the form of a socket address as used in the\n\
+    Python socket module.\n\
+\n\
+    Exceptions:\n\
+      isc.acl.ACLError Normally shouldn't happen, but still possible\n\
+                     for unexpected errors such as memory allocation\n\
+                     failure or an invalid address text being passed.\n\
+\n\
+    Parameters:\n\
+      remote_address The remote IP address\n\
+\n\
+";
+} // unnamed namespace

src/lib/python/isc/acl/dns_requestcontext_python.cc

@@ -116,18 +116,10 @@ private:
 s_RequestContext::s_RequestContext() : cppobj(NULL), data_(NULL) {
 }
 
-namespace {
-// Shortcut type which would be convenient for adding class variables safely.
-typedef CPPPyObjectContainer<s_RequestContext, RequestContext> RequestContextContainer;
-
-//
-// We declare the functions here, the definitions are below
-// the type definition of the object, since both can use the other
-//
-
-// These are the functions we export
-// For a minimal support, we don't need them.
+// Import pydoc text
+#include "dns_requestcontext_inc.cc"
 
+namespace {
 // This list contains the actual set of functions we have in
 // python. Each entry has
 // 1. Python method name
@@ -265,7 +257,7 @@ PyTypeObject requestcontext_type = {
     NULL,                               // tp_setattro
     NULL,                               // tp_as_buffer
     Py_TPFLAGS_DEFAULT,                 // tp_flags
-    "The RequestContext class objects is...(COMPLETE THIS)",
+    RequestContext_doc,
     NULL,                               // tp_traverse
     NULL,                               // tp_clear
     NULL, // tp_richcompare
@@ -294,7 +286,6 @@ PyTypeObject requestcontext_type = {
     0                                   // tp_version_tag
 };
 
-// Module Initialization, all statics are initialized here
 bool
 initModulePart_RequestContext(PyObject* mod) {
     // We initialize the static description object with PyType_Ready(),

src/lib/python/isc/acl/dnsacl_inc.cc

@@ -0,0 +1,21 @@
+namespace {
+const char* const load_request_acl_doc = "\
+load_request_acl(description) -> RequestACL\n\
+\n\
+Load a DNS ACL.\n\
+\n\
+This parses an ACL list, creates internal data for each rule\n\
+and returns a RequestACl object that contains all given rules.\n\
+\n\
+Exceptions:\n\
+  LoaderError Load failed.  The most likely cause of this is a syntax\n\
+              error in the description.  Other internal errors such as\n\
+              memory allocation failure is also converted to this\n\
+              exception.\n\
+\n\
+Parameters:\n\
+  description String representation of the JSON list of ACL.\n\
+\n\
+Return Value(s): The newly created RequestACL object\n\
+";
+} // unnamed namespace