Updated docs [skip CI]

2 files changed, 38 insertions, 21 deletions

diff --git a/docs/tests.documentation.rst b/docs/tests.documentation.rst
index c6d606c..e69cfa2 100644
--- a/docs/tests.documentation.rst
+++ b/docs/tests.documentation.rst
@@ -555,7 +555,25 @@ available. For instance:
  some data
 
 Decorator factories are most useful to framework builders. Here is an example
-that gives an idea of how you could manage permissions in a Web framework:
+that gives an idea of how you could manage permissions in a framework:
+
+.. code-block:: python
+
+ class Action(object):
+     @restricted(User)
+     def view(self):
+         "Any user can view objects"
+ 
+     @restricted(PowerUser)
+     def insert(self):
+         "Only power users can insert objects"
+ 
+     @restricted(Admin)
+     def delete(self):
+         "Only the admin can delete objects"
+
+
+where `restricted` is a decorator factory defined as follows
 
 .. code-block:: python
 
@@ -570,21 +588,6 @@ that gives an idea of how you could manage permissions in a Web framework:
              '%s does not have the permission to run %s!'
              % (self.user, func.__name__))
 
-.. code-block:: python
-
- class Action(object):
-     @restricted(User)
-     def view(self):
-         pass
- 
-     @restricted(PowerUser)
-     def insert(self):
-         pass
- 
-     @restricted(Admin)
-     def delete(self):
-         pass
-
 
 ``decorator(cls)``
 --------------------------------------------
diff --git a/src/tests/documentation.py b/src/tests/documentation.py
index 0d8ebf5..2da44c6 100644
--- a/src/tests/documentation.py
+++ b/src/tests/documentation.py
@@ -433,11 +433,25 @@ available. For instance:
  some data
 
 Decorator factories are most useful to framework builders. Here is an example
-that gives an idea of how you could manage permissions in a Web framework:
+that gives an idea of how you could manage permissions in a framework:
 
-$$restricted
 $$Action
 
+where `restricted` is a decorator factory defined as follows
+
+$$restricted
+
+In general a decorator factory has a signature
+
+.. code-block:: python
+
+  def decfactory(func, param1=default1, .., paramN=defaultN, *args, **kw):
+      ...
+
+Each parameter must have a default, so that `decfactory` can work
+as an alias for `decfactory()`, i.e. the decorator in which are parameters
+have the default value.
+
 ``decorator(cls)``
 --------------------------------------------
 
@@ -1528,15 +1542,15 @@ def restricted(func, user_class=User, *args, **kw):
 class Action(object):
     @restricted(User)
     def view(self):
-        pass
+        "Any user can view objects"
 
     @restricted(PowerUser)
     def insert(self):
-        pass
+        "Only power users can insert objects"
 
     @restricted(Admin)
     def delete(self):
-        pass
+        "Only the admin can delete objects"
 
 
 class TailRecursive(object):