Major doc update. Updates a few tests accordingly

Author: Sylvain MARIE

docs/api_reference.md

@@ -0,0 +1,48 @@
+# API reference
+
+In general, `help(symbol)` will provide the latest up-to-date documentation.
+
+## 1. inline
+
+### `validate`
+
+**todo**
+
+### `validator` / `validation`
+
+**todo**
+
+## 2. functions
+
+### `@validate_arg`
+
+**todo**
+
+### `@validate_out`
+
+**todo**
+
+### `@validate_io`
+
+**todo**
+
+## 3. classes
+
+### `@validate_field`
+
+**todo**
+
+
+## 4. internals
+
+### `Validator`
+
+**todo**
+
+### `assert_valid`
+
+**todo**
+
+### `is_valid`
+
+**todo**

docs/decorators/composition.md

@@ -149,13 +149,11 @@ def is_valid_tuple(t):
     # (c) the second element is a lowercase string of size 3
     instance_of(t[1], str)
     if len(t[1]) != 3: raise WrongLength(t[1], ref_length=3)
-    # -- finally you can write custom Failure types
+    ValidationFailurelure types
     if not t[1].islower():
         raise NotLowerCase(t[1])
 
-class NotLowerCase(Failure, ValueError):
-    """ Example custom exception class used in custom validation function. `Failure` base class provides some 
-    mechanisms to easily build the help message (same mechanisms than ValidationError)"""
+class NotLowerCase(ValidationFailurValidationFailurenisms than ValidationError)"""
     help_msg = "Value is not a lowercase string: {wrong_value}"
 ```