Add docstrings for views

user_management/api/views.py

@@ -15,6 +15,15 @@
 
 
 class GetAuthToken(ObtainAuthToken):
+    """
+    Obtain an authentication token.
+
+    Define a `POST` (create) method to authenticate a user from useing their `email` and
+    `password` and return a `token` if successful.
+    The `token` remains valid until `settings.AUTH_TOKEN_MAX_AGE` time has passed.
+
+    `DELETE` method removes the current `token` from the database.
+    """
     model = models.AuthToken
     throttle_classes = [
         throttling.UsernameLoginRateThrottle,
@@ -59,6 +68,12 @@ def delete(self, request, *args, **kwargs):
 
 
 class UserRegister(generics.CreateAPIView):
+    """
+    Register a new `User`.
+
+    An email to validate the new account is sent if `email_verification_required`
+    is set to `True`.
+    """
     serializer_class = serializers.RegistrationSerializer
     permission_classes = [permissions.IsNotAuthenticated]
 
@@ -95,6 +110,12 @@ def is_valid(self, serializer):
 
 
 class PasswordResetEmail(generics.GenericAPIView):
+    """
+    Send a password reset email to a user on request.
+
+    A user can request a password request email by providing their email address.
+    If the user is not found no error is raised.
+    """
     permission_classes = [permissions.IsNotAuthenticated]
     template_name = 'user_management/password_reset_email.html'
     serializer_class = serializers.PasswordResetEmailSerializer
@@ -122,6 +143,11 @@ def post(self, request, *args, **kwargs):
 
 
 class OneTimeUseAPIMixin(object):
+    """
+    Use a `uid` and a `token` to allow one-time access to a view.
+
+    Set user as a class attribute or raise an `InvalidExpiredToken`.
+    """
     def initial(self, request, *args, **kwargs):
         uidb64 = kwargs['uidb64']
         uid = urlsafe_base64_decode(force_text(uidb64))
@@ -143,6 +169,17 @@ def initial(self, request, *args, **kwargs):
 
 
 class PasswordReset(OneTimeUseAPIMixin, generics.UpdateAPIView):
+    """
+    Reset a user's password.
+
+    This view is generally called when a user has followed an email link to
+    reset a password.
+
+    This view will check first if the `uid` and `token` are valid.
+
+    `PasswordReset` is called with an `UPDATE` containing the new password
+    (`new_password` and `new_password2`).
+    """
     permission_classes = [permissions.IsNotAuthenticated]
     model = User
     serializer_class = serializers.PasswordResetSerializer
@@ -152,6 +189,12 @@ def get_object(self):
 
 
 class PasswordChange(generics.UpdateAPIView):
+    """
+    Change a user's password.
+
+    Give ability to `PUT` (update) a password when authenticated by submitting current
+    password.
+    """
     model = User
     permission_classes = (IsAuthenticated,)
     serializer_class = serializers.PasswordChangeSerializer
@@ -161,6 +204,11 @@ def get_object(self):
 
 
 class VerifyAccountView(OneTimeUseAPIMixin, views.APIView):
+    """
+    Verify a new user's email address.
+
+    Verify a newly created account by checking the `uid` and `token` in a `POST` request.
+    """
     permission_classes = [AllowAny]
     ok_message = _('Your account has been verified.')
 
@@ -179,6 +227,11 @@ def post(self, request, *args, **kwargs):
 
 
 class ProfileDetail(generics.RetrieveUpdateDestroyAPIView):
+    """
+    Allow a user to view and edit their profile information.
+
+    `GET`, `UPDATE` and `DELETE` current logged-in user.
+    """
     model = User
     permission_classes = (IsAuthenticated,)
     serializer_class = serializers.ProfileSerializer
@@ -188,19 +241,34 @@ def get_object(self):
 
 
 class UserList(generics.ListCreateAPIView):
+    """
+    Return information about all users and allow creation of new users.
+
+    Allow to `GET` a list users and to `POST` new user for admin user only.
+    """
     model = User
     permission_classes = (IsAuthenticated, permissions.IsAdminOrReadOnly)
     serializer_class = serializers.UserSerializerCreate
 
 
 class UserDetail(generics.RetrieveUpdateDestroyAPIView):
+    """
+    Display information about a user.
+
+    Allow admin users to update or delete user information.
+    """
     model = User
     permission_classes = (IsAuthenticated, permissions.IsAdminOrReadOnly)
     serializer_class = serializers.UserSerializer
 
 
 class ResendConfirmationEmail(generics.GenericAPIView):
-    """Resend a confirmation email."""
+    """
+    Resend a confirmation email.
+
+    `POST` request to resend a confirmation email for existing user. Useful when
+    the token has expired.
+    """
     permission_classes = [permissions.IsNotAuthenticated]
     serializer_class = serializers.ResendConfirmationEmailSerializer
     throttle_classes = [throttling.ResendConfirmationEmailRateThrottle]