Better doc

authens/backends.py

@@ -101,8 +101,8 @@ class ENSCASBackend:
         """Handles account retrieval, creation and invalidation as described above.
 
         - If no CAS account exists, create one;
-        - If a CAS account exists, but with the wrong entrance year, deprecate it
+        - If a CAS account exists, but with the wrong entrance year, convert it to
-        into an OldCASAccount;
+        an OldCASAccount instance, and create a fresh CAS Account with the correct year.
         - If a matching CAS account exists, retrieve it.
         """
 
@@ -140,6 +140,13 @@ class ENSCASBackend:
 
 
 class OldCASBackend:
+    """Authentication backend for old CAS accounts.
+
+    Given a CAS login, an entrance year and a password, first finds the matching 
+    OldCASAccount instance (if it exists), then checks the given password with
+    the user associated to this account.
+    """
+
     def authenticate(self, request, cas_login=None, password=None, entrance_year=None):
         if cas_login is None or password is None or entrance_year is None:
             return
@@ -151,7 +158,7 @@ class OldCASBackend:
             user = old_cas_acc.user
         except OldCASAccount.DoesNotExist:
             # As in Django's ModelBackend, we run the password hasher once
-            # to avoid timing attacks
+            # to mitigate timing attacks
             UserModel().set_password(password)
         else:
             if user.check_password(password) and self.user_can_authenticate(user):