diff -r 6618408c0629 -r caf268942436 pyramid_cubicweb/login.py
--- a/pyramid_cubicweb/login.py	Mon Jan 05 12:02:01 2015 +0100
+++ b/pyramid_cubicweb/login.py	Sat Jan 03 22:06:03 2015 +0100
@@ -1,3 +1,4 @@
+""" Provide login views that reproduce a classical CubicWeb behavior"""
 from pyramid import security
 from pyramid.httpexceptions import HTTPSeeOther
 from pyramid.view import view_config
@@ -9,12 +10,30 @@
 
 @view_config(route_name='login')
 def login_form(request):
+    """ Default view for the 'login' route.
+
+    Display the 'login' CubicWeb view, which is should be a login form"""
     request.response.text = render_view(request, 'login')
     return request.response
 
 
 @view_config(route_name='login', request_param=('__login', '__password'))
 def login_password_login(request):
+    """ Handle GET/POST of __login/__password on the 'login' route.
+
+    The authentication itself is delegated to the CubicWeb repository.
+
+    Request parameters:
+
+    :param __login: The user login (or email if :confval:`allow-email-login` is
+                    on.
+    :param __password: The user password
+    :param __setauthcookie: (optional) If defined and equal to '1', set the
+                            authentication cookie maxage to 1 week.
+
+                            If not, the authentication cookie is a session
+                            cookie.
+    """
     repo = request.registry['cubicweb.repository']
 
     user_eid = None
@@ -48,9 +67,13 @@
 
 @view_config(route_name='login', effective_principals=security.Authenticated)
 def login_already_loggedin(request):
+    """ 'login' route view for Authenticated users.
+
+    Simply redirect the user to '/'."""
     raise HTTPSeeOther('/')
 
 
 def includeme(config):
+    """ Create the 'login' route ('/login') and load this module views"""
     config.add_route('login', '/login')
     config.scan('pyramid_cubicweb.login')