--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/api/tools.rst	Mon Jan 26 18:04:57 2015 +0100
@@ -0,0 +1,13 @@
+.. _tools_module:
+
+:mod:`pyramid_cubicweb.tools`
+----------------------------
+
+.. automodule:: pyramid_cubicweb.tools
+
+    .. autofunction:: includeme
+
+    .. autofunction:: clone_user
+    .. autofunction:: cnx_attach_entity
+    .. autofunction:: cached_build_user
+    .. autofunction:: clear_cache

--- a/pyramid_cubicweb/tools.py	Mon Jan 26 17:59:10 2015 +0100
+++ b/pyramid_cubicweb/tools.py	Mon Jan 26 18:04:57 2015 +0100
@@ -1,4 +1,10 @@
-"""Various tools"""
+"""Various tools.
+
+.. warning::
+
+    This module should be considered as internal implementation details. Use
+    with caution, as the API may change without notice.
+"""
 
 #: A short-term cache for user clones.
 #: used by cached_build_user to speed-up repetitive calls to build_user
@@ -43,6 +49,11 @@
     with repo.internal_cnx() as cnx:
         if eid in _user_cache:
             entity = clone_user(repo, _user_cache[eid])
+            # XXX the cnx is needed here so that the CWUser instance has an
+            # access to the vreg, which it needs when its 'prefered_language'
+            # property is accessed.
+            # If this property did not need a cnx to access a vreg, we could
+            # avoid the internal_cnx() and save more time.
             cnx_attach_entity(cnx, entity)
             return entity
 
@@ -58,6 +69,10 @@
 
 
 def includeme(config):
+    """Start the cache maintenance loop task.
+
+    Automatically included by :func:`pyramid_cubicweb.make_cubicweb_application`.
+    """
     repo = config.registry['cubicweb.repository']
     interval = int(config.registry.settings.get(
         'cubicweb.usercache.expiration_time', 60*5))