Docs: better documentation of iPOPO decorators

docs/refcards/ipopo_decorators.rst

@@ -7,30 +7,98 @@ iPOPO Decorators
 Component definition
 --------------------
 
+Those decorators describe the component.
+They must decorate the factory class itself.
+
+
+Factory definition
+^^^^^^^^^^^^^^^^^^
+
+The factory definition decorator must be unique per class and must always be
+the last one executed, *i.e.* the top one in the source code.
+
 .. autoclass:: ComponentFactory
 .. autoclass:: SingletonFactory
+
+
+Component properties
+^^^^^^^^^^^^^^^^^^^^
+
 .. autoclass:: Property
 .. autoclass:: HiddenProperty
+
+Special properties
+__________________
+
+Note that some properties have a special meaning for iPOPO and Pelix.
+
+=================== ======= ====================================================
+Name                Type    Description
+=================== ======= ====================================================
+``instance.name``   ``str`` The name of the iPOPO component instance
+``service.id``      ``int`` The registration number of a service
+``service.ranking`` ``int`` The rank (priority) of the services provided by this component
+=================== ======= ====================================================
+
+.. code-block:: python
+
+    @ComponentFactory()
+    @Property('_name', 'instance.name')    # Special property
+    @Property('_value', 'my.value')        # Some property
+    @Property('_answer', 'the.answer', 42) # Some property, with a default value
+    class Foo(object):
+       def __init__(self):
+           self._name = None    # This will overwritten by iPOPO
+           self._value = 12     # 12 will be used if this property is not configured
+           self._answer = None  # 42 will be used by default
+
+
+Provided Services
+^^^^^^^^^^^^^^^^^
+
 .. autoclass:: Provides
+
+
+Requirements
+^^^^^^^^^^^^
+
 .. autoclass:: Requires
 .. autoclass:: Temporal
 .. autoclass:: RequiresBest
 .. autoclass:: RequiresMap
 .. autoclass:: RequiresVarFilter
+
+
+Instance definition
+^^^^^^^^^^^^^^^^^^^
+
 .. autoclass:: Instantiate
 
+
 Life-cycle events
 -----------------
 
+Those decorators store behavioral information on component methods.
+They must decorate methods in the component class.
+
+Component state
+^^^^^^^^^^^^^^^
+
 .. autofunction:: Validate
 .. autofunction:: Invalidate
 
+Injections
+^^^^^^^^^^
+
 .. autofunction:: Bind
 .. autoclass:: BindField
 .. autofunction:: Update
 .. autoclass:: UpdateField
 .. autofunction:: Unbind
 .. autoclass:: UnbindField
 
+Service state
+^^^^^^^^^^^^^
+
 .. autofunction:: PostRegistration
 .. autofunction:: PostUnregistration