diff --git a/addons/web/http.py b/addons/web/http.py
index d919c247bcb..0f5450ffd30 100644
--- a/addons/web/http.py
+++ b/addons/web/http.py
@@ -83,6 +83,16 @@ class WebRequest(object):
     .. attribute:: debug
 
         ``bool``, indicates whether the debug mode is active on the client
+
+    .. attribute:: db
+
+        ``str``, the name of the database linked to the current request. Can be ``None``
+        if the current request uses the @nodb decorator.
+
+    .. attribute:: uid
+
+        ``int``, the id of the user related to the current request. Can be ``None``
+        if the current request uses the @nodb or the @noauth decorator.
     """
     def __init__(self, httprequest, func, auth_method="auth"):
         self.httprequest = httprequest
@@ -135,12 +145,14 @@ class WebRequest(object):
         # we use _ as seprator where RFC2616 uses '-'
         self.lang = lang.replace('-', '_')
 
-    def authenticate(self):
+    def _authenticate(self):
         if self.auth_method == "nodb":
             self.db = None
             self.uid = None
         elif self.auth_method == "noauth":
             self.db = (self.session._db or openerp.addons.web.controllers.main.db_monodb()).lower()
+            if not self.db:
+                raise session.SessionExpiredException("No valid database for request %s" % self.httprequest)
             self.uid = None
         else: # auth
             try:
@@ -152,23 +164,26 @@ class WebRequest(object):
 
     @property
     def registry(self):
+        """
+        The registry to the database linked to this request. Can be ``None`` if the current request uses the
+        @nodb decorator.
+        """
         return openerp.modules.registry.RegistryManager.get(self.db) if self.db else None
 
     @property
     def cr(self):
+        """
+        The cursor initialized for the current method call. If the current request uses the @nodb decorator
+        trying to access this property will raise an exception.
+        """
         # some magic to lazy create the cr
         if not self._cr_cm:
             self._cr_cm = self.registry.cursor()
             self._cr = self._cr_cm.__enter__()
         return self._cr
 
-    #TODO: remove
-    @contextlib.contextmanager
-    def registry_cr(self):
-        return (self.registry, self.cr)
-
     def _call_function(self, *args, **kwargs):
-        self.authenticate()
+        self._authenticate()
         try:
             # ugly syntax only to get the __exit__ arguments to pass to self._cr
             request = self
@@ -190,10 +205,20 @@ class WebRequest(object):
 
 
 def noauth(f):
+    """
+    Decorator to put on a controller method to inform it does not require a user to be logged. When this decorator
+    is used, ``request.uid`` will be ``None``. The request will still try to detect the database and an exception
+    will be launched if there is no way to guess it.
+    """
     f.auth = "noauth"
     return f
 
 def nodb(f):
+    """
+    Decorator to put on a controller method to inform it does not require authentication nor any link to a database.
+    When this decorator is used, ``request.uid`` and ``request.db`` will be ``None``. Trying to use ``request.cr``
+    will launch an exception.
+    """
     f.auth = "nodb"
     return f
 
@@ -447,6 +472,9 @@ def set_request(request):
             _request_stack.pop()
     return with_obj()
 
+"""
+    A global proxy that always redirect to the current request object.
+"""
 request = _request_stack()
 
 #----------------------------------------------------------
diff --git a/addons/web/session.py b/addons/web/session.py
index b51c540aec5..aaa712fdedd 100644
--- a/addons/web/session.py
+++ b/addons/web/session.py
@@ -21,8 +21,10 @@ class AuthenticationError(Exception):
 class SessionExpiredException(Exception):
     pass
 
-# deprecated
 class Service(object):
+    """
+        Deprecated. Use ``openerp.netsvc.dispatch_rpc()`` instead.
+    """
     def __init__(self, session, service_name):
         self.session = session
         self.service_name = service_name
@@ -33,8 +35,10 @@ class Service(object):
             return result
         return proxy_method
 
-# deprecated
 class Model(object):
+    """
+        Deprecated. Use the resistry and cursor in ``openerp.addons.web.http.request`` instead.
+    """
     def __init__(self, session, model):
         self.session = session
         self.model = model
@@ -97,6 +101,10 @@ class OpenERPSession(object):
         self.jsonp_requests = {}     # FIXME use a LRU
 
     def authenticate(self, db, login, password, env=None):
+        """
+        Authenticate the current user with the given db, login and password. If successful, store
+        the authentication parameters in the current session and request.
+        """
         uid = openerp.netsvc.dispatch_rpc('common', 'authenticate', [db, login, password, env])
         self._db = db
         self._uid = uid
@@ -109,15 +117,21 @@ class OpenERPSession(object):
         return uid
 
     def check_security(self):
+        """
+        Chech the current authentication parameters to know if those are still valid. This method
+        should be called at each request. If the authentication fails, a ``SessionExpiredException``
+        is raised.
+        """
         if not self._db or not self._uid:
             raise SessionExpiredException("Session expired")
         import openerp.service.security as security
         security.check(self._db, self._uid, self._password)
 
     def get_context(self):
-        """ Re-initializes the current user's session context (based on
+        """
+        Re-initializes the current user's session context (based on
         his preferences) by calling res.users.get_context() with the old
-        context
+        context.
 
         :returns: the new context
         """
@@ -147,17 +161,22 @@ class OpenERPSession(object):
 
         context['lang'] = lang or 'en_US'
 
-    #deprecated
     def send(self, service_name, method, *args):
+        """
+        Deprecated. Use ``openerp.netsvc.dispatch_rpc()`` instead.
+        """
         return openerp.netsvc.dispatch_rpc(service_name, method, args)
 
-    #deprecated
     def proxy(self, service):
+        """
+        Deprecated. Use ``openerp.netsvc.dispatch_rpc()`` instead.
+        """
         return Service(self, service)
 
-    #deprecated
     def assert_valid(self, force=False):
         """
+        Deprecated. Use ``check_security()`` instead.
+
         Ensures this session is valid (logged into the openerp server)
         """
         if self._uid and not force:
@@ -167,29 +186,37 @@ class OpenERPSession(object):
         if not self._uid:
             raise AuthenticationError("Authentication failure")
 
-    #deprecated
     def ensure_valid(self):
+        """
+        Deprecated. Use ``check_security()`` instead.
+        """
         if self._uid:
             try:
                 self.assert_valid(True)
             except Exception:
                 self._uid = None
 
-    #deprecated
     def execute(self, model, func, *l, **d):
+        """
+        Deprecated. Use the resistry and cursor in ``openerp.addons.web.http.request`` instead.
+        """
         model = self.model(model)
         r = getattr(model, func)(*l, **d)
         return r
 
-    #deprecated
     def exec_workflow(self, model, id, signal):
+        """
+        Deprecated. Use the resistry and cursor in ``openerp.addons.web.http.request`` instead.
+        """
         self.assert_valid()
         r = self.proxy('object').exec_workflow(self._db, self._uid, self._password, model, signal, id)
         return r
 
-    #deprecated
     def model(self, model):
-        """ Get an RPC proxy for the object ``model``, bound to this session.
+        """
+        Deprecated. Use the resistry and cursor in ``openerp.addons.web.http.request`` instead.
+
+        Get an RPC proxy for the object ``model``, bound to this session.
 
         :param model: an OpenERP model name
         :type model: str