Add module docstring, docstrings for constructors.

(This used to be commit 67d738d6e65476263a2b7c236a57fe2b0a2dfe32)

3 files changed, 63 insertions, 14 deletions

diff --git a/source4/lib/ldb/ldb.i b/source4/lib/ldb/ldb.i
index 38a928ffb1..2c5b7535b5 100644
--- a/source4/lib/ldb/ldb.i
+++ b/source4/lib/ldb/ldb.i
@@ -25,7 +25,11 @@
    License along with this library; if not, see <http://www.gnu.org/licenses/>.
 */
 
-%module ldb
+%define DOCSTRING
+"An interface to LDB, a LDAP-like API that can either to talk an embedded database (TDB-based) or a standards-compliant LDAP server."
+%enddef
+
+%module(docstring=DOCSTRING) ldb
 
 %{
 
@@ -197,6 +201,8 @@ PyObject *ldb_val_to_py_object(struct ldb_context *ldb_ctx,
 %feature("docstring") ldb_dn "A LDB distinguished name.";
 typedef struct ldb_dn {
     %extend {
+        %feature("docstring") ldb_dn "S.__init__(ldb, string)\n" \
+                 "Create a new DN.";
         ldb_dn(ldb *ldb_ctx, const char *str)
         {
             ldb_dn *ret = ldb_dn_new(ldb_ctx, ldb_ctx, str);
@@ -216,6 +222,8 @@ fail:
         bool validate();
         const char *get_casefold();
         const char *get_linearized();
+        %feature("docstring") parent "S.parent() -> dn\n" \
+                                     "Get the parent for this DN.";
         ldb_dn *parent() { return ldb_dn_get_parent(NULL, $self); }
         int compare(ldb_dn *other);
         bool is_valid();
@@ -898,7 +906,7 @@ static char *timestring(time_t t)
 %}
 
 %rename(string_to_time) ldb_string_to_time;
-%feature("docstring") string_to_time "S.string_to_time(string) -> int\n"
+%feature("docstring") ldb_string_to_time "S.string_to_time(string) -> int\n"
                                      "Parse a LDAP time string into a UNIX timestamp.";
 time_t ldb_string_to_time(const char *s);
 
diff --git a/source4/lib/ldb/ldb.py b/source4/lib/ldb/ldb.py
index 56f34c8605..e458398b0b 100644
--- a/source4/lib/ldb/ldb.py
+++ b/source4/lib/ldb/ldb.py
@@ -3,6 +3,10 @@
 #
 # Don't modify this file, modify the SWIG interface instead.
 
+"""
+An interface to LDB, a LDAP-like API that can either to talk an embedded database (TDB-based) or a standards-compliant LDAP server.
+"""
+
 import _ldb
 import new
 new_instancemethod = new.instancemethod
@@ -67,10 +71,13 @@ CHANGETYPE_DELETE = _ldb.CHANGETYPE_DELETE
 CHANGETYPE_MODIFY = _ldb.CHANGETYPE_MODIFY
 ldb_val_to_py_object = _ldb.ldb_val_to_py_object
 class Dn(object):
-    """A LDB Distinguished name."""
+    """A LDB distinguished name."""
     thisown = _swig_property(lambda x: x.this.own(), lambda x, v: x.this.own(v), doc='The membership flag')
     def __init__(self, *args, **kwargs): 
-        """A LDB Distinguished name."""
+        """
+        S.__init__(ldb, string)
+        Create a new DN.
+        """
         _ldb.Dn_swiginit(self,_ldb.new_Dn(*args, **kwargs))
     __swig_destroy__ = _ldb.delete_Dn
     def validate(*args, **kwargs):
@@ -80,6 +87,13 @@ class Dn(object):
         """
         return _ldb.Dn_validate(*args, **kwargs)
 
+    def parent(*args, **kwargs):
+        """
+        S.parent() -> dn
+        Get the parent for this DN.
+        """
+        return _ldb.Dn_parent(*args, **kwargs)
+
     def is_special(*args, **kwargs):
         """
         S.is_special() -> bool
@@ -150,11 +164,11 @@ Dn_swigregister(Dn)
 
 ldb_msg_element_compare = _ldb.ldb_msg_element_compare
 class MessageElement(object):
-    """A message element."""
+    """Message element."""
     thisown = _swig_property(lambda x: x.this.own(), lambda x, v: x.this.own(v), doc='The membership flag')
     __repr__ = _swig_repr
     def __init__(self, *args, **kwargs): 
-        """A message element."""
+        """Message element."""
         _ldb.MessageElement_swiginit(self,_ldb.new_MessageElement(*args, **kwargs))
     __swig_destroy__ = _ldb.delete_MessageElement
     def __getitem__(self, i):
@@ -186,7 +200,7 @@ MessageElement_swigregister(MessageElement)
 
 ldb_msg_list_elements = _ldb.ldb_msg_list_elements
 class Message(object):
-    """A LDB message."""
+    """Message."""
     thisown = _swig_property(lambda x: x.this.own(), lambda x, v: x.this.own(v), doc='The membership flag')
     __repr__ = _swig_repr
     dn = _swig_property(_ldb.Message_dn_get, _ldb.Message_dn_set)
@@ -265,7 +279,7 @@ LDB_ERR_OBJECT_CLASS_MODS_PROHIBITED = _ldb.LDB_ERR_OBJECT_CLASS_MODS_PROHIBITED
 LDB_ERR_AFFECTS_MULTIPLE_DSAS = _ldb.LDB_ERR_AFFECTS_MULTIPLE_DSAS
 LDB_ERR_OTHER = _ldb.LDB_ERR_OTHER
 class Ldb(object):
-    """A connection to a LDB database."""
+    """Connection to a LDB database."""
     thisown = _swig_property(lambda x: x.this.own(), lambda x, v: x.this.own(v), doc='The membership flag')
     def __init__(self, *args, **kwargs): 
         _ldb.Ldb_swiginit(self,_ldb.new_Ldb(*args, **kwargs))
@@ -319,6 +333,14 @@ class Ldb(object):
         """
         return _ldb.Ldb_set_modules_dir(*args, **kwargs)
 
+    def set_debug(*args, **kwargs):
+        """
+        S.set_debug(callback) -> None
+        Set callback for LDB debug messages.
+        The callback should accept a debug level and debug text.
+        """
+        return _ldb.Ldb_set_debug(*args, **kwargs)
+
     def set_opaque(*args, **kwargs):
         """
         S.set_opaque(name, value) -> None
@@ -435,7 +457,13 @@ def timestring(*args, **kwargs):
     Generate a LDAP time string from a UNIX timestamp
     """
   return _ldb.timestring(*args, **kwargs)
-string_to_time = _ldb.string_to_time
+
+def string_to_time(*args, **kwargs):
+  """
+    S.string_to_time(string) -> int
+    Parse a LDAP time string into a UNIX timestamp.
+    """
+  return _ldb.string_to_time(*args, **kwargs)
 
 def register_module(*args, **kwargs):
   """
diff --git a/source4/lib/ldb/ldb_wrap.c b/source4/lib/ldb/ldb_wrap.c
index 95b71547ef..01d683245e 100644
--- a/source4/lib/ldb/ldb_wrap.c
+++ b/source4/lib/ldb/ldb_wrap.c
@@ -5727,7 +5727,10 @@ fail:
 
 static PyMethodDef SwigMethods[] = {
 	 { (char *)"ldb_val_to_py_object", (PyCFunction) _wrap_ldb_val_to_py_object, METH_VARARGS | METH_KEYWORDS, NULL},
-	 { (char *)"new_Dn", (PyCFunction) _wrap_new_Dn, METH_VARARGS | METH_KEYWORDS, (char *)"A LDB Distinguished name."},
+	 { (char *)"new_Dn", (PyCFunction) _wrap_new_Dn, METH_VARARGS | METH_KEYWORDS, (char *)"\n"
+		"S.__init__(ldb, string)\n"
+		"Create a new DN.\n"
+		""},
 	 { (char *)"delete_Dn", (PyCFunction)_wrap_delete_Dn, METH_O, NULL},
 	 { (char *)"Dn_validate", (PyCFunction)_wrap_Dn_validate, METH_O, (char *)"\n"
 		"S.validate() -> bool\n"
@@ -5735,7 +5738,10 @@ static PyMethodDef SwigMethods[] = {
 		""},
 	 { (char *)"Dn_get_casefold", (PyCFunction)_wrap_Dn_get_casefold, METH_O, NULL},
 	 { (char *)"Dn___str__", (PyCFunction)_wrap_Dn___str__, METH_O, NULL},
-	 { (char *)"Dn_parent", (PyCFunction)_wrap_Dn_parent, METH_O, NULL},
+	 { (char *)"Dn_parent", (PyCFunction)_wrap_Dn_parent, METH_O, (char *)"\n"
+		"S.parent() -> dn\n"
+		"Get the parent for this DN.\n"
+		""},
 	 { (char *)"Dn___cmp__", (PyCFunction) _wrap_Dn___cmp__, METH_VARARGS | METH_KEYWORDS, NULL},
 	 { (char *)"Dn_is_valid", (PyCFunction)_wrap_Dn_is_valid, METH_O, NULL},
 	 { (char *)"Dn_is_special", (PyCFunction)_wrap_Dn_is_special, METH_O, (char *)"\n"
@@ -5771,7 +5777,7 @@ static PyMethodDef SwigMethods[] = {
 	 { (char *)"ldb_msg_element_compare", (PyCFunction) _wrap_ldb_msg_element_compare, METH_VARARGS | METH_KEYWORDS, NULL},
 	 { (char *)"MessageElement___iter__", (PyCFunction)_wrap_MessageElement___iter__, METH_O, NULL},
 	 { (char *)"MessageElement___set__", (PyCFunction)_wrap_MessageElement___set__, METH_O, NULL},
-	 { (char *)"new_MessageElement", (PyCFunction) _wrap_new_MessageElement, METH_VARARGS | METH_KEYWORDS, (char *)"A message element."},
+	 { (char *)"new_MessageElement", (PyCFunction) _wrap_new_MessageElement, METH_VARARGS | METH_KEYWORDS, (char *)"Message element."},
 	 { (char *)"MessageElement___len__", (PyCFunction)_wrap_MessageElement___len__, METH_O, NULL},
 	 { (char *)"MessageElement_get", (PyCFunction) _wrap_MessageElement_get, METH_VARARGS | METH_KEYWORDS, NULL},
 	 { (char *)"delete_MessageElement", (PyCFunction)_wrap_delete_MessageElement, METH_O, NULL},
@@ -5829,7 +5835,11 @@ static PyMethodDef SwigMethods[] = {
 		"S.set_modules_dir(path) -> None\n"
 		"Set path LDB should search for modules\n"
 		""},
-	 { (char *)"Ldb_set_debug", (PyCFunction) _wrap_Ldb_set_debug, METH_VARARGS | METH_KEYWORDS, NULL},
+	 { (char *)"Ldb_set_debug", (PyCFunction) _wrap_Ldb_set_debug, METH_VARARGS | METH_KEYWORDS, (char *)"\n"
+		"S.set_debug(callback) -> None\n"
+		"Set callback for LDB debug messages.\n"
+		"The callback should accept a debug level and debug text.\n"
+		""},
 	 { (char *)"Ldb_set_opaque", (PyCFunction) _wrap_Ldb_set_opaque, METH_VARARGS | METH_KEYWORDS, (char *)"\n"
 		"S.set_opaque(name, value) -> None\n"
 		"Set an opaque value on this LDB connection. \n"
@@ -5871,7 +5881,10 @@ static PyMethodDef SwigMethods[] = {
 		"S.timestring(int) -> string\n"
 		"Generate a LDAP time string from a UNIX timestamp\n"
 		""},
-	 { (char *)"string_to_time", (PyCFunction) _wrap_string_to_time, METH_VARARGS | METH_KEYWORDS, NULL},
+	 { (char *)"string_to_time", (PyCFunction) _wrap_string_to_time, METH_VARARGS | METH_KEYWORDS, (char *)"\n"
+		"S.string_to_time(string) -> int\n"
+		"Parse a LDAP time string into a UNIX timestamp.\n"
+		""},
 	 { (char *)"register_module", (PyCFunction) _wrap_register_module, METH_VARARGS | METH_KEYWORDS, (char *)"\n"
 		"S.register_module(module) -> None\n"
 		"Register a LDB module.\n"