Updated documentation for /accounts and /thirdparty_auth

ACM_General/accounts/backends.py

@@ -12,9 +12,15 @@ class UserBackend(object):
 
     def authenticate(self, email=None):
         """
-        @Desc - authenticates whether or not a user is in the database based on
-                a given email. Necessary for login as Django requires
-                this function to be run on any to-be-logined user.
+        Authenticates whether or not a user is in the database based on
+        a given email. Necessary for login as Django requires
+        this function to be run on any to-be-logined user.
+
+        :param email: User provided email address.
+        :type email: String
+        :rtype: User
+        :return: The User object posessing the given email, or None
+                 if the email does not exist within the database.
         """
 
         ###
@@ -34,19 +40,31 @@ def authenticate(self, email=None):
     @staticmethod
     def user_can_authenticate(user):
         """
-        @Desc - Returns true if the user has the is_active flag set. This
-                function allows for users to be 'shut off' of opposed to
-                deleted, forcing less clean-up and increased fidelity when user
-                leaves. If is_active is false, returns False.
+        Checks for whether a user is active or not.
+        This function allows for users to be 'shut off' of opposed to
+        deleted, forcing less clean-up and increased fidelity when user
+        leaves.
+
+        :param user: User object passed in for authentication.
+        :type user: User 
+        :rtype: Boolean
+        :return: True if the user has the is_active flag set.
+                 Flase if the user's is_active flag is false.
         """
 
         is_active = getattr(user, 'is_active', None)
         return is_active or is_active is None
 
     def get_user(self, user_id):
         """
-        @Desc - Fetches the user from the database whose id (UUID) matches the
-                given user_id; otherwise, returns None.
+        Fetches the user from the database whose id (UUID) matches the
+        given user_id.
+
+        :param user_id: The UUID for which to find a user for. 
+        :type user_id: String 
+        :rtype: User
+        :return: The User object posessing the UUID or None, if the
+                 UUID does not exist withing the database.
         """
         try:
             user = User.objects.get(pk=user_id)

ACM_General/accounts/managers.py

@@ -16,18 +16,32 @@ class UserManager(BaseUserManager):
 
     def get_by_natural_key(self, email):
         """
-        @Desc - This function allows for a intutive search of the user by
-                the user's email. Similary, this can be done by running
-                User.objects.get(email=foo); however, this more standarized,
-                django approach to this.
+        Allows for a intutive search of the user by
+        the user's email. Similary, this can be done by running
+        User.objects.get(email=foo); however, this more standarized,
+        django approach to this.
+
+        :param email: The email of the user to search for.
+        :type email: String
+        :rtype: User
+        :return: The User who posseses the provided email.
         """
         return self.get(email=email)
 
     def _create_user(self, email, **extra_fields):
         """
         Base create_user function that creates a user based on fields passed
-        into it and returns the user.  extra_fields must be a member variable
-        of the class which the Manager is apart of.
+        into it and returns the user. 
+
+        :param email: The email of the user to create.
+        :type email: String
+        :param **extra_fields: Additional fields used to create the user.
+                               Items must be a member variable of the class
+                               for which the Manage is a part of.
+        :rtype: User
+        :return: The newly created User with attributes specified 
+                 in **extra_fields. If the email provided has not been
+                 whitelisted in ENFORCED_DOMAINS, return a ValueError.
         """
         if(is_valid_email(email)):
             email = self.normalize_email(email)
@@ -44,17 +58,35 @@ def _create_user(self, email, **extra_fields):
 
     def create_user(self, email, **extra_fields):
         """
-        create_user creates a user based of 'default values' that every user
+        Creates a user based of 'default values' that every user
         should adhere at registration.
+
+        :param email: The email of the user to create.
+        :type email: String
+        :param **extra_fields: Additional fields used to create the user.
+                               Items must be a member variable of the class
+                               for which the Manage is a part of.
+        :rtype: User
+        :return: Returns a User object created by universal
+                 'default values'.
         """
         extra_fields.setdefault('is_staff', False)
         extra_fields.setdefault('is_superuser', False)
         return self._create_user(email, **extra_fields)
 
     def create_superuser(self, email, **extra_fields):
         """
-        create_superuser creates a 'default' superuser which has access to
-        the django admin panel.
+        Creates a 'default' superuser which has access to
+        the Django admin panel.
+
+        :param email: The email of the user to create.
+        :type email: String
+        :param **extra_fields: Additional fields used to create the user.
+                               Items must be a member variable of the class
+                               for which the Manage is a part of.
+        :rtype: User
+        :return: User object created by universal 'default values'
+                 that posseses access to the Django admin panel.
         """
         extra_fields.setdefault('is_staff', True)
         extra_fields.setdefault('is_superuser', True)

ACM_General/accounts/models.py

@@ -15,15 +15,15 @@
 
 class User(AbstractBaseUser):
     """
-     @Desc - Overloading of the base user class to enable email validation
-             as apposed to username validation in default django
-     @Fields -
-      id - 16 character UUID which uniquely identifies each user
-      email - Stores the user's email
-      date_joined - Stores when the user signs up
-      is_active - Whether or not a user accoutn should be considered 'active'
-      is_admin - Stores whether or not the user can access the admin panel
-      objects - Container for the User Manager
+    Overloading of the base user class to enable email validation
+    as apposed to username validation in default django.
+
+    id - 16 character UUID which uniquely identifies each user
+    email - Stores the user's email
+    date_joined - Stores when the user signs up
+    is_active - Whether or not a user accoutn should be considered 'active'
+    is_admin - Stores whether or not the user can access the admin panel
+    objects - Container for the User Manager
     """
     ##
     # TODO: Integrations.
@@ -74,18 +74,27 @@ def is_admin(self):
 
     def get_full_name(self):
         """
-        @Returns: The user's full name
+        Returns the user's full name.
+
+        :rtype: String
+        :return: The user's full name.
         """
         return str(self.first_name) + " " + str(self.last_name)
 
     def get_short_name(self):
         """
-        @Returns: The user's email
+        Returns the user's email.
+
+        :rtype: String
+        :return: The user's email.
         """
         return self.email
 
     def __str__(self):
         """
-        @Returns: The user's email
+        Returns the user's email.
+
+        :rtype: String
+        :return: The user's email.
         """
         return self.email

ACM_General/accounts/serializers.py

@@ -16,7 +16,13 @@ class Meta:
     @staticmethod
     def validate_email(email):
         """
-        Ensure the domain of the email is mst.edu
+        Ensure the domain of the email is mst.edu.
+
+        :param email: The provided email.
+        :type email: String
+        :rtype: Boolean
+        :return: True if the email has a domain of mst.edu,
+                 otherwise Error. 
         """
 
         if is_valid_email(email):
@@ -28,7 +34,13 @@ def validate_email(email):
     def create(self, validated_data):
         """
         Create and return an instance of the User model designated by the
-        validated_data if no ValidationErrors were raised
+        validated_data if no ValidationErrors were raised.
+
+        :param validated_data: Data used for the creation of a new 
+                               User instance..
+        :type validated_data: Dictionary (?)
+        :rtype: User 
+        :return: An instance of the User model defined by validated_data.
         """
 
         return models.User.objects.create(**validated_data)