documentation and docstring updates

tiramisu/autolib.py

@@ -22,16 +22,25 @@
 from tiramisu.error import PropertiesOptionError, ConfigError
 from tiramisu.i18n import _
 # ____________________________________________________________
-# automatic Option object
-#def special_owner_factory(name, owner, value,
-#                          callback, callback_params=None, config=None):
-#    # in case of an 'auto' and a 'fill' without a value,
-#    # we have to carry out a calculation
-#    return calc_factory(name, callback, callback_params, config)
 
+def carry_out_calculation(name,
+                          config,
+                          callback,
+                          callback_params,
+                          index=None):
+    """a function that carries out a calculation for an option's value
 
-def carry_out_calculation(name, config, callback, callback_params, index=None):
-    "a function that carries out a calculation for an option's value"
+    :param name: the option name (`opt._name`)
+    :param config: the context config in order to have
+                   the whole options available
+    :param callback: the name of the callback function
+    :type callback: str
+    :param callback_params: the callback's parameters
+                            (only keyword parameters are allowed)
+    :type callback_params: dict
+    :param index: if an option is multi, only calculates the nth value
+    :type index: int
+    """
     #callback, callback_params = option.getcallback()
     #if callback_params is None:
     #    callback_params = {}
@@ -121,6 +130,7 @@ def carry_out_calculation(name, config, callback, callback_params, index=None):
 
 
 def calculate(name, callback, params, tcparams):
+    # FIXME we don't need the option's name down there.
     """wrapper that launches the 'callback'
 
     :param callback: callback name

tiramisu/value.py

@@ -40,19 +40,27 @@ class Values(object):
         :param context: the context is the home config's values
 
         """
-
         self.context = context
+        # the storage type is dictionary or sqlite3
         import_lib = 'tiramisu.storage.{0}.value'.format(storage_type)
         self._p_ = __import__(import_lib, globals(), locals(), ['Values'],
                               -1).Values(storage)
 
     def _getkey(self, opt):
+        """depends on the storage utility.
+        typically, the option's path in the parent `Config` or `SubConfig`
+        """
         if self._p_.key_is_path:
             return self._get_opt_path(opt)
         else:
             return opt
 
     def _getdefault(self, opt):
+        """
+        actually retrieves the default value
+
+        :param opt: the `option.Option()` object
+        """
         meta = self.context.cfgimpl_get_meta()
         if meta is not None:
             value = meta.cfgimpl_get_values()[opt]
@@ -64,7 +72,11 @@ class Values(object):
             return value
 
     def _getvalue(self, opt, validate=True):
-        "return value or default value if not set"
+        """actually retrieves the value
+
+        :param opt: the `option.Option()` object
+        :returns: the option's value (or the default value if not set)
+        """
         key = self._getkey(opt)
         if not self._p_.hasvalue(key):
             # if no value
@@ -83,13 +95,16 @@ class Values(object):
         return self._p_.get_modified_values()
 
     def __contains__(self, opt):
+        """
+        implements the 'in' keyword syntax in order provide a pythonic way
+        to kow if an option have a value
+
+        :param opt: the `option.Option()` object
+        """
         return self._p_.hasvalue('value', self._getkey(opt))
 
     def __delitem__(self, opt):
-        """overrides the builtins `del()` instructions 
-        
-        if you use this you are responsible for all bad things happening
-        """
+        """overrides the builtins `del()` instructions"""
         self.reset(opt)
 
     def reset(self, opt):
@@ -115,6 +130,14 @@ class Values(object):
         return False
 
     def _getcallback_value(self, opt, index=None):
+        """
+        retrieves a value for the options that have a callback
+
+        :param opt: the `option.Option()` object
+        :param index: if an option is multi, only calculates the nth value
+        :type index: int
+        :returns: a calculated value
+        """
         callback, callback_params = opt._callback
         if callback_params is None:
             callback_params = {}
@@ -124,6 +147,7 @@ class Values(object):
                                      index=index)
 
     def __getitem__(self, opt):
+        "enables us to use the pythonic dictionnary-like access to values"
         return self.getitem(opt)
 
     def getitem(self, opt, validate=True, force_permissive=False,
@@ -227,8 +251,8 @@ class Values(object):
     def getowner(self, opt):
         """
         retrieves the option's owner
-        
-        :param opt: the `option.Option` object 
+
+        :param opt: the `option.Option` object
         :returns: a `setting.owners.Owner` object
         """
         if isinstance(opt, SymLinkOption):
@@ -242,8 +266,8 @@ class Values(object):
     def setowner(self, opt, owner):
         """
         sets a owner to an option
-        
-        :param opt: the `option.Option` object 
+
+        :param opt: the `option.Option` object
         :param owner: a valid owner, that is a `setting.owners.Owner` object
         """
         if not isinstance(owner, owners.Owner):
@@ -272,9 +296,9 @@ class Values(object):
 
     def _get_opt_path(self, opt):
         """
-        retrieve the option's path in the config 
-        
-        :param opt: the `option.Option` object 
+        retrieve the option's path in the config
+
+        :param opt: the `option.Option` object
         :returns: a string with points like "gc.dummy.my_option"
         """
         return self.context.cfgimpl_get_description().impl_get_path_by_opt(opt)