From 632de1cffb74959ce57146fd2e9e3d2205798c24 Mon Sep 17 00:00:00 2001
From: Emmanuel Garette <egarette@cadoles.com>
Date: Sat, 7 Sep 2013 22:16:50 +0200
Subject: [PATCH] comment tiramisu/setting.py

---
 tiramisu/setting.py | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/tiramisu/setting.py b/tiramisu/setting.py
index 1dba144..249af37 100644
--- a/tiramisu/setting.py
+++ b/tiramisu/setting.py
@@ -308,7 +308,7 @@ class Settings(object):
         return str(list(self._getproperties()))
 
     def __getitem__(self, opt):
-        path = self._get_opt_path(opt)
+        path = self._get_path_by_opt(opt)
         return self._getitem(opt, path)
 
     def _getitem(self, opt, path):
@@ -325,7 +325,7 @@ class Settings(object):
             self._p_.reset_all_propertives()
         else:
             if opt is not None and _path is None:
-                _path = self._get_opt_path(opt)
+                _path = self._get_path_by_opt(opt)
             self._p_.reset_properties(_path)
         self.context().cfgimpl_reset_cache()
 
@@ -453,7 +453,7 @@ class Settings(object):
                     instead of passing a :class:`tiramisu.option.Option()` object.
         """
         if opt is not None and path is None:
-            path = self._get_opt_path(opt)
+            path = self._get_path_by_opt(opt)
         if not isinstance(permissive, tuple):
             raise TypeError(_('permissive must be a tuple'))
         self._p_.setpermissive(path, permissive)
@@ -484,6 +484,11 @@ class Settings(object):
         self._read(rw_remove, rw_append)
 
     def reset_cache(self, only_expired):
+        """reset all settings in cache
+
+        :param only_expired: if True reset only expired cached values
+        :type only_expired: boolean
+        """
         if only_expired:
             self._p_.reset_expired_cache(int(time()))
         else:
@@ -499,12 +504,13 @@ class Settings(object):
 
         let's have a look at all the tuple's items:
 
-        - **option** is the target option's name or path
+        - **option** is the target option's
 
-        - **expected** is the target option's value that is going to trigger an action
+        - **expected** is the target option's value that is going to trigger
+          an action
 
-        - **action** is the (property) action to be accomplished if the target option
-          happens to have the expected value
+        - **action** is the (property) action to be accomplished if the target
+          option happens to have the expected value
 
         - if **inverse** is `True` and if the target option's value does not
           apply, then the property action must be removed from the option's
@@ -541,7 +547,7 @@ class Settings(object):
             for require in requires:
                 option, expected, action, inverse, \
                     transitive, same_action = require
-                reqpath = self._get_opt_path(option)
+                reqpath = self._get_path_by_opt(option)
                 if reqpath == path or reqpath.startswith(path + '.'):
                     raise RequirementError(_("malformed requirements "
                                              "imbrication detected for option:"
@@ -572,5 +578,10 @@ class Settings(object):
                     break
         return calc_properties
 
-    def _get_opt_path(self, opt):
+    def _get_path_by_opt(self, opt):
+        """just a wrapper to get path in optiondescription's cache
+
+        :param opt: `Option`'s object
+        :returns: path
+        """
         return self.context().cfgimpl_get_description().impl_get_path_by_opt(opt)