From 7dab4e22edd50f3dd6be886a160f5d7dd231e4e4 Mon Sep 17 00:00:00 2001
From: nukleus <stefan.valouch@hadiko.de>
Date: Fri, 25 Nov 2011 14:36:51 +0100
Subject: [PATCH] [ldapom] Improve doxygen documentation.

Adds member and return documentation to some functions. Note that as per
https://bugzilla.gnome.org/show_bug.cgi?id=537436 one should not use doxygen
and docstrings documentation at the same time. This commit however only focuses
on doxygen comments.
---
 Doxyfile  |  2 +-
 ldapom.py | 40 +++++++++++++++++++++++++++++++++-------
 2 files changed, 34 insertions(+), 8 deletions(-)

diff --git a/Doxyfile b/Doxyfile
index f28dae0..1a1669b 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -230,7 +230,7 @@ OPTIMIZE_OUTPUT_VHDL   = NO
 # (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions 
 # you also need to set FILE_PATTERNS otherwise the files are not read by doxygen.
 
-EXTENSION_MAPPING      = Python
+EXTENSION_MAPPING      = py=Python
 
 # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want 
 # to include (a tag file for) the STL sources as input, then you should 
diff --git a/ldapom.py b/ldapom.py
index 7333866..d44f9b0 100644
--- a/ldapom.py
+++ b/ldapom.py
@@ -23,6 +23,11 @@
 # TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
+## @mainpage
+# The @e ldapom python module provides a simple LDAP object mapper.
+# @author Florian Richter
+#
+
 import ldap
 
 LDAPOM_VERBOSE = False
@@ -331,11 +336,13 @@ def new_ldap_node(self, dn):
 
 class LdapAttribute(object):
     """
-        Holds an set of LDAP-Attributes with the same name.
-        All changes are recorded, so they can be push to ldap_modify
-        directly
+        Holds a set of LDAP-Attributes with the same name.
+        
+        All changes are recorded, so they can be pushed to ldap_modify directly.
     """
 
+    ## Creates a new attribute with the given @p name and @p value. If @p add is @e False (default), the current value
+    # is overwritten, else appended.
     def __init__(self, name, value, add=False):
         self._name = unicode(name)
         self._replace_all = False
@@ -370,7 +377,7 @@ def __unicode__(self):
             return self._values[0]
         return unicode(self._values)
 
-    ## @return String
+    ## @returns the String representation of the object.
     def __repr__(self):
         """
         literal representation
@@ -397,18 +404,23 @@ def remove(self, value):
             self._values.remove(unicode(value))
             self._changes.append((ldap.MOD_DELETE, self._name, unicode(value)))
 
+    ## Membership test operator (<em>in</em> and <em>not in</em>), tests if the attribute contains the @p item.
     ## @return Boolean
     def __contains__(self, item):
         return self._values.__contains__(item)
 
-    ## @return String
+    ## @returns the item identified by @p key
     def __getitem__(self, key):
         return self._values[key]
 
+    ## Sets the value of @p key to @p value.
+    # @return None
     def __setitem__(self, key, value):
         self._replace_all = True
         self._values[key] = unicode(value)
 
+    ## Deletes the value identified by its @p key
+    # @return None
     def __delitem__(self, key):
         self._replace_all = True
         self._values.remove(key)
@@ -417,10 +429,11 @@ def __delitem__(self, key):
     def __iter__(self):
         return self._values.__iter__()
 
+    ## Sets single @p value, discards all existing ones.
     ## @return None
     def set_value(self, value):
         """
-        set single value, discard all existing ones
+        Sets single value, discards all existing ones
         """
         if type(value) == list:
             self._values = [unicode(x) for x in value]
@@ -457,6 +470,10 @@ class LdapNode(object):
     without network traffic.
     """
 
+    ## Creates the node using the given connection and dn.
+    # @param conn The connection string
+    # @param dn The DN to use
+    # @param new default: @e False
     def __init__(self, conn, dn, new=False):
         """
         Create lazy Node Object from dn
@@ -488,10 +505,11 @@ def _load_attributes(self, attributes_dict):
                 for attr_name, attr_values in attributes_dict.items()
         ])
 
+    ## @returns the value of the attribute identified by its @p name. Attributes starting with <em>is_*</em> are mapped
+    # to a check, if the objectClass is present.
     def __getattr__(self, name):
         """
             get an ldap-attribute
-            * attributes starting with is_* are mapped to a check, if the objectClass is present
         """
         if self._attr == None:
             self.retrieve_attributes()
@@ -501,6 +519,8 @@ def __getattr__(self, name):
             return self._attr[name]
         raise AttributeError('Cannot find attribute %s' % name)
 
+    ## Sets the @p value of the attribute identified by its @p name.
+    # @return None
     def __setattr__(self, name, value):
         "set ldap attribute"
         # handle private attributes the default way
@@ -513,21 +533,27 @@ def __setattr__(self, name, value):
         else:
             self._attr[name] = LdapAttribute(name, value, add=True)
 
+    ## Deletes the attribute identified by its @p name.
+    # @return None
     def __delattr__(self, name):
         if self._attr == None:
             self.retrieve_attributes()
         del self._attr[name]
         self._to_delete.append(name)
 
+    ## @returns the unicode DN of the node.
     def __unicode__(self):
         return self._dn
 
+    ## @returns the string DN of the node.
     def __str__(self):
         return self._dn.encode("utf-8")
 
+    ## @returns the String representation of the object.
     def __repr__(self):
         return "<LdapNode: %s>" % self._dn
 
+    ## Saves any changes made to the object.
     ## @return None
     def save(self):
         """