--- a/pyramid_cubicweb/profile.py	Mon Jan 05 12:02:01 2015 +0100
+++ b/pyramid_cubicweb/profile.py	Sat Jan 03 22:06:03 2015 +0100
@@ -1,3 +1,6 @@
+""" Tools for profiling.
+
+See :ref:`profiling`."""
 import cProfile
 import itertools
 from pyramid.view import view_config
@@ -5,18 +8,40 @@
 
 @view_config(route_name='profile_ping')
 def ping(request):
+    """ View that handle '/_profile/ping'
+
+    It simply reply 'ping', without requiring connection to the repository.
+    It is a useful as a comparison point to evaluate the actual overhead of
+    more costly views.
+    """
     request.response.text = u'pong'
     return request.response
 
 
 @view_config(route_name='profile_cnx')
 def cnx(request):
+    """ View that handle '/_profile/cnx'
+
+    Same as :func:`ping`, but it first ask for a connection to the repository.
+    Useful to evaluate the overhead of opening a connection.
+    """
     request.cw_cnx
     request.response.text = u'pong'
     return request.response
 
 
 def wsgi_profile(app, filename='program.prof', dump_every=50):
+    """ A WSGI middleware for profiling
+
+    It enable the profiler before passing the request to the underlying
+    application, and disable it just after.
+
+    The stats will be dumped after ``dump_every`` requests
+
+    :param filename: The filename to dump the stats to.
+    :param dump_every: Number of requests after which to dump the stats.
+    """
+
     profile = cProfile.Profile()
 
     counter = itertools.count(1)