refactoring the doc for the 0.55 new API

tiramisu/error.py

@@ -20,42 +20,35 @@
 # the whole pypy projet is under MIT licence
 # ____________________________________________________________
 
-#ValueError if function's parameter not correct
-#           or if not logical
-#           or if validation failled
-#           or multi must be a list
-#           or error in autolib
-#TypeError if parameter has no good type
-#AttributeError if no option or optiondescription in optiondescription (also when specified a path)
-
-
-#____________option___________
+# Exceptions for an Option
 class PropertiesOptionError(AttributeError):
-    "try to access to opt with not allowed property"
+    "attempt to access to an option with a property that is'nt allowed"
     def __init__(self, msg, proptype):
         self.proptype = proptype
         super(PropertiesOptionError, self).__init__(msg)
 
 
-#____________config___________
+#____________________________________________________________
+# Exceptions for a Config
 class ConfigError(StandardError):
-    """try to change owner for an option without value
-    or if _cfgimpl_descr is None
-    or if error in calculation"""
+    """attempt to change an option's owner without a value
+    or in case of `_cfgimpl_descr` is None
+    or if a calculation cannot be carried out"""
     pass
 
 
 class ConflictError(StandardError):
-    "duplicate config"
+    "duplicate options are present in a single config"
     pass
 
 
-#____________other___________
+#____________________________________________________________
+# miscellaneous exceptions
 class RequirementRecursionError(StandardError):
-    "recursive error"
+    "a recursive loop occurs in the requirements tree"
     pass
 
 
 class SlaveError(StandardError):
-    "problem with slave's length"
+    "problem with a slave's value length"
     pass

tiramisu/option.py

@@ -348,6 +348,11 @@ class Option(BaseInformation):
 
 
 class ChoiceOption(Option):
+    """Represents a choice out of several objects.
+
+    The option can also have the value ``None``
+    """
+
     __slots__ = ('_values', '_open_values', '_opt_type')
     _opt_type = 'string'
 
@@ -355,6 +360,9 @@ class ChoiceOption(Option):
                  requires=None, multi=False, callback=None,
                  callback_params=None, open_values=False, validator=None,
                  validator_args=None, properties=()):
+        """
+        :param values: is a list of values the option can possibly take
+        """
         if not isinstance(values, tuple):
             raise TypeError(_('values must be a tuple for {0}').format(name))
         self._values = values
@@ -386,6 +394,7 @@ class ChoiceOption(Option):
 
 
 class BoolOption(Option):
+    "Represents a choice between ``True`` and ``False``"
     __slots__ = ('_opt_type',)
     _opt_type = 'bool'
 
@@ -394,6 +403,7 @@ class BoolOption(Option):
 
 
 class IntOption(Option):
+    "Represents a choice of an integer"
     __slots__ = ('_opt_type',)
     _opt_type = 'int'
 
@@ -402,6 +412,7 @@ class IntOption(Option):
 
 
 class FloatOption(Option):
+    "Represents a choice of a floating point number"
     __slots__ = ('_opt_type',)
     _opt_type = 'float'
 
@@ -410,6 +421,7 @@ class FloatOption(Option):
 
 
 class StrOption(Option):
+    "Represents the choice of a string"
     __slots__ = ('_opt_type',)
     _opt_type = 'string'
 
@@ -418,6 +430,7 @@ class StrOption(Option):
 
 
 class UnicodeOption(Option):
+    "Represents the choice of a unicode string"
     __slots__ = ('_opt_type',)
     _opt_type = 'unicode'
     _empty = u''
@@ -446,6 +459,7 @@ class SymLinkOption(object):
 
 
 class IPOption(Option):
+    "Represents the choice of an ip"
     __slots__ = ('_opt_type', '_only_private')
     _opt_type = 'ip'
 
@@ -475,6 +489,7 @@ class IPOption(Option):
 
 
 class NetworkOption(Option):
+    "Represents the choice of a network"
     __slots__ = ('_opt_type',)
     _opt_type = 'network'
 
@@ -487,6 +502,7 @@ class NetworkOption(Option):
 
 
 class NetmaskOption(Option):
+    "Represents the choice of a netmask"
     __slots__ = ('_opt_type',)
     _opt_type = 'netmask'