[1179] update docstrings

src/lib/python/isc/datasrc/client_inc.cc

@@ -3,13 +3,13 @@ namespace {
 const char* const DataSourceClient_doc = "\
 The base class of data source clients.\n\
 \n\
-This is an abstract base class that defines the common interface for\n\
-various types of data source clients. A data source client is a top\n\
-level access point to a data source, allowing various operations on\n\
-the data source such as lookups, traversing or updates. The client\n\
-class itself has limited focus and delegates the responsibility for\n\
-these specific operations to other classes; in general methods of this\n\
-class act as factories of these other classes.\n\
+This is the python wrapper for the abstract base class that defines\n\
+the common interface for various types of data source clients. A data\n\
+source client is a top level access point to a data source, allowing \n\
+various operations on the data source such as lookups, traversing or \n\
+updates. The client class itself has limited focus and delegates \n\
+the responsibility for these specific operations to other (c++) classes;\n\
+in general methods of this class act as factories of these other classes.\n\
 \n\
 - InMemoryClient: A client of a conceptual data source that stores all\n\
   necessary data in memory for faster lookups\n\
@@ -49,49 +49,30 @@ server). In order to avoid a surprising disruption with a naive copy\n\
 it's prohibited explicitly. For the expected usage of the client\n\
 classes the restriction should be acceptable.\n\
 \n\
-TodoThis class is still not complete. It will need more factory\n\
+Todo: This class is still not complete. It will need more factory\n\
 methods, e.g. for (re)loading a zone.\n\
-\n\
-DataSourceClient()\n\
-\n\
-    Default constructor.\n\
-\n\
-    This is intentionally defined as protected as this base class\n\
-    should never be instantiated directly.\n\
-\n\
-    The constructor of a concrete derived class may throw an\n\
-    exception. This interface does not specify which exceptions can\n\
-    happen (at least at this moment), and the caller should expect any\n\
-    type of exception and react accordingly.\n\
-\n\
 ";
 
 const char* const DataSourceClient_findZone_doc = "\
-find_zone(name) -> FindResult\n\
+find_zone(name) -> (code, ZoneFinder)\n\
 \n\
 Returns a ZoneFinder for a zone that best matches the given name.\n\
 \n\
-- code: The result code of the operation.result.SUCCESS: A zone that\n\
-  gives an exact match is foundresult.PARTIALMATCH: A zone whose\n\
-  origin is a super domain of name is found (but there is no exact\n\
-  match)result.NOTFOUND: For all other cases.\n\
-- result.SUCCESS: A zone that gives an exact match is found\n\
-- result.PARTIALMATCH: A zone whose origin is a super domain of name\n\
+code: The result code of the operation (integer).\n\
+- DataSourceClient.SUCCESS: A zone that gives an exact match is found\n\
+- DataSourceClient.PARTIALMATCH: A zone whose origin is a super domain of name\n\
   is found (but there is no exact match)\n\
-- result.NOTFOUND: For all other cases.\n\
-- zone_finder: Pointer to a ZoneFinder object for the found zone if\n\
-  one is found; otherwise NULL.\n\
+- DataSourceClient.NOTFOUND: For all other cases.\n\
+ZoneFinder: ZoneFinder object for the found zone if one is found;\n\
+otherwise None.\n\
 \n\
-A specific derived version of this method may throw an exception. This\n\
-interface does not specify which exceptions can happen (at least at\n\
-this moment), and the caller should expect any type of exception and\n\
-react accordingly.\n\
+Any internal error will be raised as an isc.datasrc.Error exception\n\
 \n\
 Parameters:\n\
   name       A domain name for which the search is performed.\n\
 \n\
-Return Value(s): A FindResult object enclosing the search result (see\n\
-above).\n\
+Return Value(s): A tuple containing a result value and a ZoneFinder object or\n\
+None\n\
 ";
 
 const char* const DataSourceClient_getIterator_doc = "\
@@ -103,9 +84,9 @@ This allows for traversing the whole zone. The returned object can\n\
 provide the RRsets one by one.\n\
 \n\
 This throws isc.datasrc.Error when the zone does not exist in the\n\
-datasource.\n\
+datasource, or when an internal error occurs.\n\
 \n\
-The default implementation throws isc.NotImplemented. This allows for\n\
+The default implementation throws isc.datasrc.NotImplemented. This allows for\n\
 easy and fast deployment of minimal custom data sources, where the\n\
 user/implementator doesn't have to care about anything else but the\n\
 actual queries. Also, in some cases, it isn't possible to traverse the\n\
@@ -115,8 +96,8 @@ It is not fixed if a concrete implementation of this method can throw\n\
 anything else.\n\
 \n\
 Parameters:\n\
-  name       The name of zone apex to be traversed. It doesn't do\n\
-             nearest match as find_zone.\n\
+  isc.dns.Name The name of zone apex to be traversed. It doesn't do\n\
+               nearest match as find_zone.\n\
 \n\
 Return Value(s): Pointer to the iterator.\n\
 ";
@@ -152,7 +133,7 @@ case as handling multiple incoming AXFR streams concurrently, but this\n\
 interface does not even prohibit an attempt of getting more than one\n\
 updater for the same zone, as long as the underlying data source\n\
 allows such an operation (and any conflict resolution is left to the\n\
-specific derived class implementation).\n\
+specific implementation).\n\
 \n\
 If replace is true, any existing RRs of the zone will be deleted on\n\
 successful completion of updates (after commit() on the updater); if\n\
@@ -160,13 +141,13 @@ it's false, the existing RRs will be intact unless explicitly deleted\n\
 by delete_rrset() on the updater.\n\
 \n\
 A data source can be \"read only\" or can prohibit partial updates. In\n\
-such cases this method will result in an isc.NotImplemented exception\n\
+such cases this method will result in an isc.datasrc.NotImplemented exception\n\
 unconditionally or when replace is false).\n\
 \n\
 Exceptions:\n\
-  NotImplemented The underlying data source does not support updates.\n\
+  isc.datasrc. NotImplemented The underlying data source does not support\n\
+               updates.\n\
   isc.datasrc.Error Internal error in the underlying data source.\n\
-  std.bad_alloc Resource allocation failure.\n\
 \n\
 Parameters:\n\
   name       The zone name to be updated\n\

src/lib/python/isc/datasrc/finder_inc.cc

@@ -2,10 +2,10 @@ namespace {
 const char* const ZoneFinder_doc = "\
 The base class to search a zone for RRsets.\n\
 \n\
-The ZoneFinder class is an abstract base class for representing an\n\
+The ZoneFinder class is a wrapper for the c++ base class for representing an\n\
 object that performs DNS lookups in a specific zone accessible via a\n\
 data source. In general, different types of data sources (in-memory,\n\
-database-based, etc) define their own derived classes of ZoneFinder,\n\
+database-based, etc) define their own derived c++ classes of ZoneFinder,\n\
 implementing ways to retrieve the required data through the common\n\
 interfaces declared in the base class. Each concrete ZoneFinder object\n\
 is therefore (conceptually) associated with a specific zone of one\n\
@@ -26,13 +26,6 @@ results for the same name and type can be different if other threads\n\
 or programs make updates to the zone between the lookups. We should\n\
 revisit this point as we gain more experiences.\n\
 \n\
-ZoneFinder()\n\
-\n\
-    The default constructor.\n\
-\n\
-    This is intentionally defined as protected as this base class\n\
-    should never be instantiated (except as part of a derived class).\n\
-\n\
 ";
 
 const char* const ZoneFinder_getOrigin_doc = "\
@@ -50,7 +43,7 @@ Return the RR class of the zone.\n\
 ";
 
 const char* const ZoneFinder_find_doc = "\
-find(name, type, target=NULL, options=FIND_DEFAULT) -> FindResult\n\
+find(name, type, target=NULL, options=FIND_DEFAULT) -> (code, FindResult)\n\
 \n\
 Search the zone for a given pair of domain name and RR type.\n\
 \n\
@@ -69,7 +62,7 @@ Search the zone for a given pair of domain name and RR type.\n\
   and the code of SUCCESS will be returned.\n\
 - If the search name matches a delegation point of DNAME, it returns\n\
   the code of DNAME and that DNAME RR.\n\
-- If the target isn't NULL, all RRsets under the domain are inserted\n\
+- If the target is a list, all RRsets under the domain are inserted\n\
   there and SUCCESS (or NXDOMAIN, in case of empty domain) is returned\n\
   instead of normall processing. This is intended to handle ANY query.\n\
   : this behavior is controversial as we discussed in\n\
@@ -77,6 +70,7 @@ Search the zone for a given pair of domain name and RR type.\n\
   We should revisit the interface before we heavily rely on it. The\n\
   options parameter specifies customized behavior of the search. Their\n\
   semantics is as follows:\n\
+  (This feature is disable at this time)\n\
 - GLUE_OK Allow search under a zone cut. By default the search will\n\
   stop once it encounters a zone cut. If this option is specified it\n\
   remembers information about the highest zone cut and continues the\n\
@@ -86,11 +80,8 @@ Search the zone for a given pair of domain name and RR type.\n\
   the search has encountered a zone cut, DELEGATION with the\n\
   information of the highest zone cut will be returned.\n\
 \n\
-A derived version of this method may involve internal resource\n\
-allocation, especially for constructing the resulting RRset, and may\n\
-throw an exception if it fails. It throws DuplicateRRset exception if\n\
-there are duplicate rrsets under the same domain. It should not throw\n\
-other types of exceptions.\n\
+This method raises an isc.datasrc.Error exception if there is an internal\n\
+error in the datasource.\n\
 \n\
 Parameters:\n\
   name       The domain name to be searched for.\n\
@@ -99,7 +90,7 @@ Parameters:\n\
              into it.\n\
   options    The search options.\n\
 \n\
-Return Value(s): A FindResult object enclosing the search result (see\n\
-above).\n\
+Return Value(s): A tuple of a result code an a FindResult object enclosing\n\
+the search result (see above).\n\
 ";
 } // unnamed namespace

src/lib/python/isc/datasrc/iterator_inc.cc

@@ -3,9 +3,9 @@ namespace {
 const char* const ZoneIterator_doc = "\
 Read-only iterator to a zone.\n\
 \n\
-You can get an instance of (descendand of) ZoneIterator from\n\
+You can get an instance of the ZoneIterator from\n\
 DataSourceClient.get_iterator() method. The actual concrete\n\
-implementation will be different depending on the actual data source\n\
+c++ implementation will be different depending on the actual data source\n\
 used. This is the abstract interface.\n\
 \n\
 There's no way to start iterating from the beginning again or return.\n\
@@ -14,21 +14,21 @@ The ZoneIterator is a python iterator, and can be iterated over directly.\n\
 ";
 
 const char* const ZoneIterator_getNextRRset_doc = "\
-get_next_rrset() -> isc.dns.ConstRRset\n\
+get_next_rrset() -> isc.dns.RRset\n\
 \n\
 Get next RRset from the zone.\n\
 \n\
-This returns the next RRset in the zone as a shared pointer. The\n\
-shared pointer is used to allow both accessing in-memory data and\n\
-automatic memory management.\n\
+This returns the next RRset in the zone.\n\
 \n\
 Any special order is not guaranteed.\n\
 \n\
 While this can potentially throw anything (including standard\n\
 allocation errors), it should be rare.\n\
 \n\
-Pointer to the next RRset or NULL pointer when the iteration gets to\n\
+Pointer to the next RRset or None pointer when the iteration gets to\n\
 the end of the zone.\n\
 \n\
+Raises an isc.datasrc.Error exception if it is called again after returning\n\
+None\n\
 ";
 } // unnamed namespace

src/lib/python/isc/datasrc/updater_inc.cc

@@ -14,14 +14,14 @@ some form of \"begin transaction\" statement for the database.\n\
 Updates (adding or deleting RRs) are made via add_rrset() and\n\
 delete_rrset() methods. Until the commit() method is called the\n\
 changes are local to the updater object. For example, they won't be\n\
-visible via a ZoneFinder object except the one returned by the\n\
-updater's own find() method. The commit() completes the\n\
-transaction and makes the changes visible to others.\n\
+visible via a ZoneFinder object, but only by the updater's own find()\n\
+method. The commit() completes the transaction and makes the changes\n\
+visible to others.\n\
 \n\
 This class does not provide an explicit \"rollback\" interface. If\n\
 something wrong or unexpected happens during the updates and the\n\
 caller wants to cancel the intermediate updates, the caller should\n\
-simply destruct the updater object without calling commit(). The\n\
+simply destroy the updater object without calling commit(). The\n\
 destructor is supposed to perform the \"rollback\" operation,\n\
 depending on the internal details of the derived class.\n\
 \n\
@@ -32,10 +32,10 @@ It may be revisited as we gain more experiences.\n\
 ";
 
 const char* const ZoneUpdater_addRRset_doc = "\
-add_rrset(rrset) -> void\n\
+add_rrset(rrset) -> No return value\n\
 \n\
 Add an RRset to a zone via the updater.\n\
-\n\
+It performs a few basic checks:\n\
 - Whether the RR class is identical to that for the zone to be updated\n\
 - Whether the RRset is not empty, i.e., it has at least one RDATA\n\
 - Whether the RRset is not associated with an RRSIG, i.e., whether\n\
@@ -76,7 +76,7 @@ This method must not be called once commit() is performed. If it calls\n\
 after commit() the implementation must throw a isc.datasrc.Error\n\
 exception.\n\
 \n\
-TodoAs noted above we may have to revisit the design details as we\n\
+Todo As noted above we may have to revisit the design details as we\n\
 gain experiences:\n\
 \n\
 - we may want to check (and maybe reject) if there is already a\n\
@@ -92,8 +92,7 @@ gain experiences:\n\
 \n\
 Exceptions:\n\
   isc.datasrc.Error Called after commit(), RRset is invalid (see above),\n\
-             internal data source error\n\
-  std.bad_alloc Resource allocation failure\n\
+                    internal data source error, or wrapper error\n\
 \n\
 Parameters:\n\
   rrset      The RRset to be added\n\
@@ -101,7 +100,7 @@ Parameters:\n\
 ";
 
 const char* const ZoneUpdater_deleteRRset_doc = "\
-delete_rrset(rrset) -> void\n\
+delete_rrset(rrset) -> No return value\n\
 \n\
 Delete an RRset from a zone via the updater.\n\
 \n\
@@ -120,20 +119,21 @@ on the initial implementation decisions.\n\
 Ignoring the TTL may not look sensible, but it's based on the\n\
 observation that it will result in more intuitive result, especially\n\
 when the underlying data source is a general purpose database. See\n\
-also DatabaseAccessor.delete_record_in_zone() on this point. It also\n\
-matches the dynamic update protocol (RFC2136), where TTLs are ignored\n\
-when deleting RRs.\n\
+also the c++ documentation of DatabaseAccessor::DeleteRecordInZone()\n\
+on this point. It also matches the dynamic update protocol (RFC2136),\n\
+where TTLs are ignored when deleting RRs.\n\
 \n\
+This method performs a limited level of validation on the specified\n\
+RRset:\n\
 - Whether the RR class is identical to that for the zone to be updated\n\
 - Whether the RRset is not empty, i.e., it has at least one RDATA\n\
-- Whether the RRset is not associated with an RRSIG, i.e., whether\n\
-  get_rrsig() on the RRset returns a NULL pointer.\n\
+- Whether the RRset is not associated with an RRSIG\n\
 \n\
 This method must not be called once commit() is performed. If it calls\n\
 after commit() the implementation must throw a isc.datasrc.Error\n\
 exception.\n\
 \n\
-TodoAs noted above we may have to revisit the design details as we\n\
+Todo: As noted above we may have to revisit the design details as we\n\
 gain experiences:\n\
 \n\
 - we may want to check (and maybe reject) if some or all of the RRs\n\
@@ -175,7 +175,7 @@ must result in a isc.datasrc.Error exception.\n\
 \n\
 Exceptions:\n\
   isc.datasrc.Error Duplicate call of the method, internal data source\n\
-             error\n\
+             error, or wrapper error\n\\n\
 \n\
 ";
 } // unnamed namespace