# HG changeset patch
# User Nicolas Chauvat <nicolas.chauvat@logilab.fr>
# Date 1301599479 -7200
# Node ID 7469fd77f48f3b3b76558fc0cdf4ae6de9700232
# Parent  4bab50b029272ffc05af0d3600bc33c16d37c9dc
[doc] improve dostring of server.hook

diff -r 4bab50b02927 -r 7469fd77f48f server/hook.py
--- a/server/hook.py	Thu Mar 31 17:12:27 2011 +0200
+++ b/server/hook.py	Thu Mar 31 21:24:39 2011 +0200
@@ -93,7 +93,7 @@
 unset), specific events are issued and the Hooks matching these events
 are called.
 
-You can get the event that triggered a hook by accessing its :attr:event
+You can get the event that triggered a hook by accessing its `event`
 attribute.
 
 .. _`dataflow`: http://en.wikipedia.org/wiki/Dataflow
@@ -105,68 +105,64 @@
 When called for one of these events, hook will have an `entity` attribute
 containing the entity instance.
 
-* `before_add_entity`, `before_update_entity`:
+- `before_add_entity`, `before_update_entity`:
 
-  - on those events, you can check what attributes of the entity are modified in
-    `entity.cw_edited` (by definition the database is not yet updated in a before
-    event)
+  On those events, you can access the modified attributes of the entity using
+  the `entity.cw_edited` dictionnary. The values can be modified and the old
+  values can be retrieved.
+
+  If you modify the `entity.cw_edited` dictionnary in the hook, that is before
+  the database operations take place, you will avoid the need to process a whole
+  new rql query and the underlying backend query (eg usually sql) will contain
+  the modified data. For example:
 
-  - you are allowed to further modify the entity before database
-    operations, using the dictionary notation on `cw_edited`. By doing
-    this, you'll avoid the need for a whole new rql query processing,
-    the only difference is that the underlying backend query (eg
-    usually sql) will contains the additional data. For example:
+  .. sourcecode:: python
 
-    .. sourcecode:: python
+     self.entity.cw_edited['age'] = 42
 
-       self.entity.set_attributes(age=42)
+  will modify the age before it is written to the backend storage.
 
-    will set the `age` attribute of the entity to 42. But to do so, it will
-    generate a rql query that will have to be processed, then trigger some
-    hooks, and so one (potentially leading to infinite hook loops or such
-    awkward situations..) You can avoid this by doing the modification that way:
+  Similarly, removing an attribute from `cw_edited` will cancel its
+  modification:
 
-    .. sourcecode:: python
+  .. sourcecode:: python
 
-       self.entity.cw_edited['age'] = 42
+     del self.entity.cw_edited['age']
 
-    Here the attribute will simply be edited in the same query that the
-    one that triggered the hook.
+  On a `before_update_entity` event, you can access the old and new values:
 
-    Similarly, removing an attribute from `cw_edited` will cancel its
-    modification.
+  .. sourcecode:: python
 
-  - on `before_update_entity` event, you can access to old and new values in
-    this hook, by using `entity.cw_edited.oldnewvalue(attr)`
+     old, new = entity.cw_edited.oldnewvalue('age')
+
+- `after_add_entity`, `after_update_entity`
 
+  On those events, you can get the list of attributes that were modified using
+  the `entity.cw_edited` dictionnary, but you can not modify it or get the old
+  value of an attribute.
 
-* `after_add_entity`, `after_update_entity`
+- `before_delete_entity`, `after_delete_entity`
 
-  - on those events, you can still check what attributes of the entity are
-    modified in `entity.cw_edited` but you can't get anymore the old value, nor
-    modify it.
+  On those events, the entity has no `cw_edited` dictionnary.
 
-* `before_delete_entity`, `after_delete_entity`
-
-  - on those events, the entity has no `cw_edited` set.
-
+.. note:: `self.entity.set_attributes(age=42)` will set the `age` attribute to
+  42. But to do so, it will generate a rql query that will have to be processed,
+  hence may trigger some hooks, etc. This could lead to infinitely looping hooks.
 
 Relation modification related events
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When called for one of these events, hook will have `eidfrom`, `rtype`, `eidto`
-attributes containing respectivly the eid of the subject entity, the relation
+attributes containing respectively the eid of the subject entity, the relation
 type and the eid of the object entity.
 
 * `before_add_relation`, `before_delete_relation`
 
-  - on those events, you can still get original relation by issuing a rql query
+  On those events, you can still get the original relation by issuing a rql query.
 
 * `after_add_relation`, `after_delete_relation`
 
-This is an occasion to remind us that relations support the add / delete
-operation, but no update.
-
+Take note that relations can be added or deleted, but not updated.
 
 Non data events
 ~~~~~~~~~~~~~~~