--- a/doc/book/en/devrepo/repo/sessions.rst	Thu Mar 21 19:08:07 2013 +0100
+++ b/doc/book/en/devrepo/repo/sessions.rst	Fri Mar 22 19:31:21 2013 +0100
@@ -199,3 +199,8 @@
      if hasattr(req.cnx, 'foo_user') and req.foo_user:
          return 1
      return 0
+
+Full API Session
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: cubicweb.server.session.Session

--- a/server/session.py	Thu Mar 21 19:08:07 2013 +0100
+++ b/server/session.py	Fri Mar 22 19:31:21 2013 +0100
@@ -48,28 +48,28 @@
 
 @objectify_predicate
 def is_user_session(cls, req, **kwargs):
-    """repository side only predicate returning 1 if the session is a regular
-    user session and not an internal session
-    """
+    """return 1 when session is not internal.
+
+    This predicate can only be used repository side only. """
     return not req.is_internal_session
 
 @objectify_predicate
 def is_internal_session(cls, req, **kwargs):
-    """repository side only predicate returning 1 if the session is not a regular
-    user session but an internal session
-    """
+    """return 1 when session is not internal.
+
+    This predicate can only be used repository side only. """
     return req.is_internal_session
 
 @objectify_predicate
 def repairing(cls, req, **kwargs):
-    """repository side only predicate returning 1 if the session is not a regular
-    user session but an internal session
-    """
+    """return 1 when repository is running in repair mode"""
     return req.vreg.config.repairing
 
 
 class transaction(object):
-    """context manager to enter a transaction for a session: when exiting the
+    """Ensure that the transaction is either commited or rollbacked at exit
+
+    Context manager to enter a transaction for a session: when exiting the
     `with` block on exception, call `session.rollback()`, else call
     `session.commit()` on normal exit
     """
@@ -124,8 +124,9 @@
 
 
 class security_enabled(object):
-    """context manager to control security w/ session.execute, since by
-    default security is disabled on queries executed on the repository
+    """context manager to control security w/ session.execute,
+
+    By default security is disabled on queries executed on the repository
     side.
     """
     def __init__(self, session, read=None, write=None):
@@ -142,14 +143,22 @@
 
 
 class TransactionData(object):
+    """Small object hold core Transaction data"""
     def __init__(self, txid):
+        #: transaction unique id
         self.transactionid = txid
+        #: reentrance handling
         self.ctx_count = 0
 
 
 class Session(RequestSessionBase):
-    """Repository usersession, tie a session id, user, connections set and
-    other session data all together.
+    """Repository user session
+
+    This tie all together:
+     * session id,
+     * user,
+     * connections set,
+     * other session data.
 
     About session storage / transactions
     ------------------------------------
@@ -172,6 +181,7 @@
 
       :attr:`_threads_in_transaction` is a set of (thread, connections set)
       referencing threads that currently hold a connections set for the session.
+    .. automethod:: cubicweb.server.session.transaction
 
     You should not have to use neither :attr:`_txdata` nor :attr:`__threaddata`,
     simply access transaction data transparently through the :attr:`_threaddata`
@@ -184,11 +194,24 @@
       this may also be used as a communication channel between the client and
       the repository.
 
+    .. automethod:: cubicweb.server.session.Session.get_shared_data
+    .. automethod:: cubicweb.server.session.Session.set_shared_data
+    .. automethod:: cubicweb.server.session.Session.added_in_transaction
+    .. automethod:: cubicweb.server.session.Session.deleted_in_transaction
+
+    Transaction state information:
+
+      :attr:`running_dbapi_query`, boolean flag telling if the executing query
+      is coming from a dbapi connection or is a query from within the repository
+
       :attr:`cnxset`, the connections set to use to execute queries on sources.
       During a transaction, the connection set may be freed so that is may be
       used by another session as long as no writing is done. This means we can
       have multiple sessions with a reasonably low connections set pool size.
 
+    .. automethod:: cubicweb.server.session.set_cnxset
+    .. automethod:: cubicweb.server.session.free_cnxset
+
       :attr:`mode`, string telling the connections set handling mode, may be one
       of 'read' (connections set may be freed), 'write' (some write was done in
       the connections set, it can't be freed before end of the transaction),
@@ -204,9 +227,24 @@
       'uncommitable' (some :exc:`ValidationError` or :exc:`Unauthorized` error
       has been raised during the transaction and so it must be rollbacked).
 
+    .. automethod:: cubicweb.server.session.Session.commit
+    .. automethod:: cubicweb.server.session.Session.rollback
+    .. automethod:: cubicweb.server.session.Session.close
+    .. automethod:: cubicweb.server.session.Session.closed
+
+    Security level Management:
+
       :attr:`read_security` and :attr:`write_security`, boolean flags telling if
       read/write security is currently activated.
 
+    .. automethod:: cubicweb.server.session.Session.set_write_security
+    .. automethod:: cubicweb.server.session.Session.set_read_security
+    .. automethod:: cubicweb.server.session.Session.init_security
+    .. automethod:: cubicweb.server.session.Session.reset_security
+    .. automethod:: cubicweb.server.session.Session.security_enabled
+
+    Hooks Management:
+
       :attr:`hooks_mode`, may be either `HOOKS_ALLOW_ALL` or `HOOKS_DENY_ALL`.
 
       :attr:`enabled_hook_categories`, when :attr:`hooks_mode` is
@@ -215,12 +253,23 @@
       :attr:`disabled_hook_categories`, when :attr:`hooks_mode` is
       `HOOKS_ALLOW_ALL`, this set contains hooks categories that are disabled.
 
+    .. automethod:: cubicweb.server.session.Session.deny_all_hooks_but
+    .. automethod:: cubicweb.server.session.Session.allow_all_hooks_but
+    .. automethod:: cubicweb.server.session.Session.is_hook_category_activated
+    .. automethod:: cubicweb.server.session.Session.is_hook_activated
 
-      :attr:`running_dbapi_query`, boolean flag telling if the executing query
-      is coming from a dbapi connection or is a query from within the repository
+    Data manipulation:
+
+    .. automethod:: cubicweb.server.session.Session.add_relation
+    .. automethod:: cubicweb.server.session.Session.add_relations
+    .. automethod:: cubicweb.server.session.Session.delete_relation
 
-    .. automethod:: cubicweb.server.session.deny_all_hooks_but
-    .. automethod:: cubicweb.server.session.all_all_hooks_but
+    Other:
+
+    .. automethod:: cubicweb.server.session.Session.call_service
+
+
+
     """
     is_request = False
     is_internal_session = False
@@ -246,6 +295,7 @@
         self.set_language(user.prefered_language())
         # internals
         self._tx_data = {}
+        # Data local to the thread
         self.__threaddata = threading.local()
         self._threads_in_transaction = set()
         self._closed = False