documentation update

doc/consistency.txt

@@ -1,7 +1,9 @@
 .. default-role:: literal
 
+.. currentmodule:: tiramisu
+
 The global consistency
-========================================
+===========================
 
 Identical option names
 ----------------------
@@ -19,12 +21,15 @@ Option's values type validation
 --------------------------------
 
 When a value is set to the option, the value is validated by the
-option's `option.Option()` validator's type.
+option's :class:`option.Option()` validator's type.
 
 Notice that if the option is `multi`, that is the `multi` attribute is set to
 `True`, then the validation of the option value accepts a list of values
 of the same type.
 
+For example, an :class:`option.IntOption` validator waits for an `int` object of 
+course, an :class:`option.StrOption` validator waits for an `str`, vs...
+
 Requirements
 ------------
 

doc/index.txt

@@ -46,3 +46,5 @@ Indices and tables
 This work is licensed under a `Creative Commons Attribution-ShareAlike 3.0 Unported License`_.
 
 .. _`Creative Commons Attribution-ShareAlike 3.0 Unported License`: http://creativecommons.org/licenses/by-sa/3.0/deed.en_US
+
+.. todolist:: 

doc/status.txt

@@ -6,7 +6,9 @@ Local statuses and global setting
 Available configuration statuses
 ----------------------------------
 
-The configuration's status lives in an `setting.Setting` object.
+.. currentmodule:: tiramisu
+
+The configuration's status lives in an :class:`setting.Setting()` object.
 This configuration status corresponds to specific attributes or bunch of
 attributes that can be accessed together with some `setting.Setting`
 method:
@@ -18,7 +20,7 @@ method:
     possible to modify a disabled option.
 
     To enable read-write status, call
-    `congi.Config.read_write()`
+    :class:`config.CommonConfig.read_write()`
 
 **read only status**
 
@@ -29,7 +31,7 @@ method:
     The configuration has not an access to the hidden options
     but can read the disabled options.
 
-    To enable read only status, call `config.Config.read_only()`
+    To enable read only status, call :class:`config.SubConfig.read_only()`
 
 .. csv-table:: **Configuration's statuses summary**
    :header: " ", "Hidden", "Disabled", "Mandatory"
@@ -42,24 +44,24 @@ method:
 Freezing a configuration
 ---------------------------
 
+.. todo:: freeze at configuration level
+
 At the configuration level, `setting.Setting.freeze` freezes
 the whole configuration options.
 
-- `test_option_type.test_frozen_value()`
-- `test_option_type.test_freeze()`
-
 .. _`frozen`:
 
-It is possible to *freeze* a single `Option` object with
+It is possible to *freeze* a single :class:`option.Option()` object with
-`option.Option.freeze()`. If you try to modify a frozen option, it
+:meth:`config.SubConfig.cfgimpl_get_settings()`. If you try to modify a frozen 
-raises a `TypeError: trying to change a frozen option object`.
+:option, it raises a `TypeError: trying to change a frozen option object`.
 
-- `test_option_type.test_freeze_one_option()`
+To find out if an option `myoption` is frozen, just make an assertion on the 
-
+settings like that::
-Moreover, frozen option can return his default value if
+    
-`option.Option.force_default()` has been called on this option,
+    'frozen' in cfg.cfgimpl_get_settings()[myoption]
-see `test_option_default.test_force_default_on_freeze()`
 
+Moreover, frozen option can return their default values if
+`option.Option.force_default()` is called on this option.
 
 Restricted access to an `Option()`
 -----------------------------------
@@ -97,19 +99,23 @@ to activate, deactivate properties::
 Value owners
 -------------
 
-.. method:: tiramisu.config.Config.getowner() 
+
+Every configuration option has a **owner**. When the option is instanciated, 
+the owner is :obj:`setting.owners.default` because a default value has been set 
+(including `None`, wich means that no value has been set yet).
+
+.. method:: config.CommonConfig.getowner() 
 
    This method can retrieve an Option's owner. 
 
-Every configuration option has a **owner**. When the option is
+- At the instance of the `Config` object, the value owner is 
-instanciated, the owner is `default` because a default value has been
+  :obj:`setting.owners.default` because
-set (including `None`, take a look at the tests).
+  the default values are set at the instance of the configuration option 
-
+  object,
-- At the instance of the `Config` object, the value owner is `owners.default` because
-  the default values are set at the instance of the configuration option object,
-
-- at the modification of an option, the owner is `owners.default`, (which is `user`)
 
+- at the modification of an option, the owner is `owners.default`, (which is 
+  :obj:`owners.user`)
+  
 Special behaviors for an option
 ---------------------------------
 

tiramisu/setting.py

@@ -261,22 +261,34 @@ class Setting(object):
     def validate_properties(self, opt_or_descr, is_descr, is_write,
                             value=None, force_permissive=False,
                             force_properties=None):
-        #opt properties
+        """
+        validation upon the properties related to `opt_or_descr` 
+        
+        :param opt_or_descr: an option or an option description object
+        :param force_permissive: behaves as if the permissive property was present 
+        :param is_descr: we have to know if we are in an option description, 
+                         just because the mandatory property doesn't exist there 
+                         
+        :param is_write: in the validation process, an option is to be modified,
+                         the behavior can be different (typically with the `frozen` 
+                         property)
+        """
+        # opt properties
         properties = copy(self._get_properties(opt_or_descr))
-        #remove opt permissive
+        # remove opt permissive
         properties -= self._get_permissive(opt_or_descr)
-        #remove global permissive if need
+        # remove global permissive if need
         self_properties = copy(self._get_properties())
         if force_permissive is True or 'permissive' in self_properties:
             properties -= self._get_permissive()
 
-        #global properties
+        # global properties
         if force_properties is not None:
             self_properties.update(force_properties)
 
-        #calc properties
+        # calc properties
         properties &= self_properties
-        #mandatory and frozen are special properties
+        # mandatory and frozen are special properties
         if is_descr:
             properties -= frozenset(('mandatory', 'frozen'))
         else:
@@ -288,7 +300,7 @@ class Setting(object):
                 properties.add('frozen')
             elif 'frozen' in properties and not is_write:
                 properties.remove('frozen')
-
+        # at this point an option should not remain in properties 
         if properties != frozenset():
             props = list(properties)
             if 'frozen' in properties: