[2542] Update doc for create_zone wrapper

And a minor cleanup in the code

src/lib/datasrc/client.h

@@ -368,7 +368,7 @@ public:
     /// \return The number of zones known to this datasource
     virtual unsigned int getZoneCount() const;
 
-    /// \brief Create a zone in the database
+    /// \brief Create a zone in the data source
     ///
     /// Creates a new (empty) zone in the data source backend, which
     /// can subsequently be filled with data (through getUpdater()).

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

@@ -89,18 +89,32 @@ None\n\
 ";
 
 const char* const DataSourceClient_createZone_doc = "\
-create_zone(name) -> boolean\n\
+create_zone(name) -> bool\n\
 \n\
-Creates a new (empty) zone in the data source backend.\n\
+Create a zone in the data source.\n\
 \n\
-Datasources can throw isc.NotImplemented\n\
+Creates a new (empty) zone in the data source backend, which can\n\
+subsequently be filled with data (through get_updater()).\n\
 \n\
-Any other internal error will be raised as an isc.datasrc.Error exception\n\
+Note: This is a tentative API, and this method is likely to change or\n\
+be removed in the near future. For that reason, it currently provides\n\
+a default implementation that throws NotImplemented.\n\
+\n\
+Apart from the two exceptions mentioned below, in theory this call can\n\
+throw anything, depending on the implementation of the datasource\n\
+backend.\n\
+\n\
+Exceptions:\n\
+  NotImplemented If the datasource backend does not support direct\n\
+             zone creation.\n\
+  DataSourceError If something goes wrong in the data source while\n\
+             creating the zone.\n\
 \n\
 Parameters:\n\
-  name       A (fully qualified) domain name for the zone to be created.\n\
+  name       The (fully qualified) name of the zone to create\n\
 \n\
-Return Value(s): True if the zone has been created, False if it already existed\n\
+Return Value(s): True if the zone was added, False if it already\n\
+existed\n\
 ";
 
 const char* const DataSourceClient_getIterator_doc = "\

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

@@ -97,8 +97,7 @@ DataSourceClient_createZone(PyObject* po_self, PyObject* args) {
     PyObject* name;
     if (PyArg_ParseTuple(args, "O!", &name_type, &name)) {
         try {
-            const bool result = self->client->createZone(PyName_ToName(name));
-            if (result) {
+            if (self->client->createZone(PyName_ToName(name))) {
                 Py_RETURN_TRUE;
             } else {
                 Py_RETURN_FALSE;