Document the authentication module API

src/sso_server/sso_server/auth/__init__.py

@@ -32,10 +32,41 @@ class AuthBase(object):
         self.config = config
 
     def authenticate(self, username, password, otp=None):
+        """Authenticate a user.
+
+        Args:
+          username: username (utf-8 encoded string).
+          password: password (utf-8 encoded string).
+          otp: OTP token, if provided by the user. Note that this
+              should be a string, not an integer.
+        Returns:
+          A boolean result indicating successful authentication.
+        """
         return False
 
     def match_groups(self, username, groups):
+        """Match user groups against requested ones.
+
+        Args:
+          username: username (utf-8 encoded string).
+          groups: collection (list, set) of requested groups. Group
+              names are strings.
+        Returns:
+          An unsorted collection (set) containing the intersection of
+          the groups that the user is a member of and the requested
+          groups.
+        """
         return set()
 
     def get_user_email(self, username):
+        """Return the email address associated with a user.
+
+        The SAML module requires this information: some endpoints
+        (Gitlab, for instance) make use of it to match local records.
+
+        Args:
+          username: username (utf-8 encoded string).
+        Returns:
+          The email address associated with the user, or None.
+        """
         return None