Improve docs (#19)

api/resources/auth.py

@@ -148,10 +148,10 @@ def delete(self, user_id):
         __Returns__:
             
         This method does not return content as per default for HTTP Status Code 204
-
         """
 
         # TODO: Blacklist the Token?
         app.redis.delete(f'auth|{user_id}')
 
         return make_response('[HTTP_204_NO_CONTENT]', HttpStatusCode.HTTP_204_NO_CONTENT)
+

api/resources/event.py

@@ -1,3 +1,20 @@
+# -*- coding: utf-8 -*-
+""" Event module which holds all the logic for handling events.
+
+Currently the event is represented by the arguments of the HTTP request, which are:
+
+- Name - [Required]
+- Start datetime - [Required]
+- End datetime - [Required]
+- Max guests allowed - [Required]
+- Cuisine - [Required]
+- Price per person - [Request]
+- Description - [Request]
+- Guests - [Not Required and only available for `put`]
+- Rating - [Not Required and only available for `put`]
+
+"""
+
 from flask import make_response, current_app as app
 from flask_restful import Resource, reqparse
 from datetime import datetime
@@ -19,6 +36,18 @@
 class Event(Resource):
 
     def __init__(self):
+        """
+        This class represents the event resource.
+        
+        Here also a copy of the request parser is made and all 
+        arguments are set as not required as for `get` and `put`
+        required arguments are not needed. 
+
+        The request parser is extended for `put` with following arguments: 
+        - `guests`
+        - `rating`
+        """
+
         self.parser = base_parser.copy()
 
         # TODO: Use list comprehension with new symbol in Python 3.8: 
@@ -30,6 +59,16 @@ def __init__(self):
         self.parser.add_argument('rating', location='json')
 
     def get(self, id):
+        """
+        This method returns the event found by id.
+        
+        __Returns:__
+
+        * If id is invalid: A json response with the text [HTTP_400_BAD_REQUEST]
+        * If event not found: A json response with the text [HTTP_404_NOT_FOUND]
+        * If success: A json response with the event data
+        """
+
         if not ObjectId.is_valid(id):
             return make_response('[HTTP_400_BAD_REQUEST]', HttpStatusCode.HTTP_400_BAD_REQUEST)
 
@@ -46,6 +85,16 @@ def get(self, id):
 
     @token_required
     def put(self, user_id, id):
+        """
+        This method updates the event and is only accessible with authentication token.
+        
+        __Returns:__
+
+        * If id is invalid: A json response with the text [HTTP_400_BAD_REQUEST]
+        * If event not found: A json response with the text [HTTP_404_NOT_FOUND]
+        * If success: No content as per default for HTTP Status Code 204
+        """
+
         if not ObjectId.is_valid(id):
             return make_response('[HTTP_400_BAD_REQUEST]', HttpStatusCode.HTTP_400_BAD_REQUEST)
 
@@ -78,11 +127,19 @@ def put(self, user_id, id):
 
 
 class EventList(Resource):
-
-    def __init__(self):
-        self.parser = base_parser.copy()
+    """
+    This class represents events resource.
+    """
 
     def get(self):
+        """
+        This method returns the list of events.
+        
+        __Returns:__
+
+        A json response with list of events or an empty list if no events in the database
+        """
+
         response = []
         events = app.mongo.db.events.find()
 
@@ -94,7 +151,15 @@ def get(self):
 
     @token_required
     def post(self, user_id):
-        args = self.parser.parse_args()
+        """
+        This method creates a new event.
+        
+        __Returns:__
+
+        * If success: A json response with the text [HTTP_201_CREATED]
+        """
+
+        args = base_parser.parse_args()
 
         events = app.mongo.db.events
 

api/resources/user.py

@@ -1,3 +1,18 @@
+# -*- coding: utf-8 -*-
+""" User module which holds all the logic of the application user.
+
+Currently the user is represented by the arguments of the HTTP request, which are:
+
+- Email - [Required]
+- First name - [Required]
+- Last name - [Required]
+- Password - [Required]
+- Phone number - [Required]
+- Is Host - [Not Required and only available for `put`]
+- Rating - [Not Required and only available for `put`]
+
+"""
+
 from flask import make_response, current_app as app
 from flask_restful import Resource, reqparse
 from datetime import datetime
@@ -17,8 +32,22 @@
 
 
 class User(Resource):
+    """
+    """
 
     def __init__(self):
+        """
+        This class represents the user resource.
+        
+        Here also a copy of the request parser is made and all 
+        arguments are set as not required as for `get` and `put`
+        required arguments are not needed. 
+
+        The request parser is extended for `put` with following arguments: 
+        - `is_host`
+        - `rating`
+        """
+
         self.parser = base_parser.copy()
 
         for arg in self.parser.args:
@@ -28,6 +57,16 @@ def __init__(self):
         self.parser.add_argument('rating', location='json')
 
     def get(self, id):
+        """
+        This method returns the user found by id.
+        
+        __Returns:__
+
+        * If id is invalid: A json response with the text [HTTP_400_BAD_REQUEST]
+        * If user not found: A json response with the text [HTTP_404_NOT_FOUND]
+        * If success: A json response with the user data
+        """
+
         if not ObjectId.is_valid(id):
             return make_response('[HTTP_400_BAD_REQUEST]', HttpStatusCode.HTTP_400_BAD_REQUEST)
 
@@ -46,6 +85,16 @@ def get(self, id):
 
     @token_required
     def put(self, user_id, id):
+        """
+        This method updates the user and is only accessible with authentication token.
+        
+        __Returns:__
+
+        * If id is invalid: A json response with the text [HTTP_400_BAD_REQUEST]
+        * If user not found: A json response with the text [HTTP_404_NOT_FOUND]
+        * If success: No content as per default for HTTP Status Code 204
+        """
+
         if not ObjectId.is_valid(id):
             return make_response('[HTTP_400_BAD_REQUEST]', HttpStatusCode.HTTP_400_BAD_REQUEST)
 
@@ -63,6 +112,7 @@ def put(self, user_id, id):
         fields = {key: value for key,
                   value in args.items() if value is not None}
 
+        # The update occurs only if arguments have been passed via request
         if len(fields):
             users.update_one({'_id': object_id},
                             {
@@ -79,11 +129,19 @@ def put(self, user_id, id):
 
 
 class UserList(Resource):
-
-    def __init__(self):
-        self.parser = base_parser.copy()
+    """
+    This class represents users resource.
+    """
 
     def get(self):
+        """
+        This method returns the list of users.
+        
+        __Returns:__
+
+        A json response with list of users or an empty list if no users in the database
+        """
+
         response = []
         users = app.mongo.db.users.find()
 
@@ -97,7 +155,16 @@ def get(self):
         return make_response({'data': response}, HttpStatusCode.HTTP_200_OK)
 
     def post(self):
-        args = self.parser.parse_args()
+        """
+        This method creates a new user.
+        
+        __Returns:__
+
+        * If user already exists: A json response with the text [HTTP_409_CONFLICT]
+        * If success: A json response with the text [HTTP_201_CREATED]
+        """
+
+        args = base_parser.parse_args()
 
         email = args['email'].strip()
 

docs/api/resources/auth.html

@@ -175,7 +175,6 @@ <h1 class="title">Module <code>api.resources.auth</code></h1>
         __Returns__:
 
         This method does not return content as per default for HTTP Status Code 204
-
         &#34;&#34;&#34;
 
         # TODO: Blacklist the Token?
@@ -457,7 +456,6 @@ <h3>Methods</h3>
         __Returns__:
 
         This method does not return content as per default for HTTP Status Code 204
-
         &#34;&#34;&#34;
 
         # TODO: Blacklist the Token?
@@ -499,7 +497,6 @@ <h3>Methods</h3>
     __Returns__:
 
     This method does not return content as per default for HTTP Status Code 204
-
     &#34;&#34;&#34;
 
     # TODO: Blacklist the Token?