diff -r 6618408c0629 -r caf268942436 pyramid_cubicweb/bwcompat.py
--- a/pyramid_cubicweb/bwcompat.py	Mon Jan 05 12:02:01 2015 +0100
+++ b/pyramid_cubicweb/bwcompat.py	Sat Jan 03 22:06:03 2015 +0100
@@ -15,7 +15,11 @@
 
 class PyramidSessionHandler(object):
     """A CW Session handler that rely on the pyramid API to fetch the needed
-    informations"""
+    informations.
+
+    It implements the :class:`cubicweb.web.application.CookieSessionHandler`
+    API.
+    """
 
     def __init__(self, appli):
         self.appli = appli
@@ -28,6 +32,11 @@
 
 
 class CubicWebPyramidHandler(object):
+    """ A Pyramid request handler that rely on a cubicweb instance to do the
+    whole job
+
+    :param appli: A CubicWeb 'Application' object.
+    """
     def __init__(self, appli):
         self.appli = appli
 
@@ -107,6 +116,12 @@
 
 
 class TweenHandler(object):
+    """ A Pyramid tween handler that submit unhandled requests to a Cubicweb
+    handler.
+
+    The CubicWeb handler to use is expected to be in the pyramid registry, at
+    key ``'cubicweb.handler'``.
+    """
     def __init__(self, handler, registry):
         self.handler = handler
         self.cwhandler = registry['cubicweb.handler']
@@ -124,10 +139,22 @@
 
 
 def includeme(config):
-    # Set up a tween app that will handle the request if the main application
-    # raises a HTTPNotFound exception.
-    # This is to keep legacy compatibility for cubes that makes use of the
-    # cubicweb controllers.
+    """ Set up a tween app that will handle the request if the main application
+    raises a HTTPNotFound exception.
+
+    This is to keep legacy compatibility for cubes that makes use of the
+    cubicweb urlresolvers.
+
+    It provides, for now, support for cubicweb controllers, but this feature
+    will be reimplemented separatly in a less compatible way.
+
+    It is automatically included by the configuration system, but can be
+    disabled in the :ref:`pyramid_settings`:
+
+    .. code-block:: ini
+
+        cubicweb.bwcompat = no
+    """
     cwconfig = config.registry['cubicweb.config']
     repository = config.registry['cubicweb.repository']
     cwappli = CubicWebPublisher(