From fdf4aebc61c5422d21a26eb7c990c157b376112d Mon Sep 17 00:00:00 2001
From: benne238 <benne238@purdue.edu>
Date: Mon, 29 Mar 2021 15:08:34 -0400
Subject: [PATCH] update api.py docstrings

---
 webqueue2_api/api.py | 152 +++++++++++++++++++++++++------------------
 1 file changed, 87 insertions(+), 65 deletions(-)

diff --git a/webqueue2_api/api.py b/webqueue2_api/api.py
index 7fcefa4..f32a90d 100644
--- a/webqueue2_api/api.py
+++ b/webqueue2_api/api.py
@@ -109,20 +109,24 @@ class Login(Resource):
     def post(self) -> tuple:
         """Validates username/password and returns both access and refresh tokens.
 
-        Return Codes:
-                200 (OK): On success.
-                401 (Unauthroized): When username or password are incorrect.
-                422 (Unprocessable Entitiy): When the username or password can't be parsed.
-
-        Example:
-                curl -X POST
-                    -H "Content-Type: application/json" 
-                    -d '{"username": "bob", "password": "super_secret"}'
-
-                { "access_token": fjr09hfp09h932jp9ruj3.3r8ihf8h0w8hr08ifhj804h8i.8h48ith08ity409hip0t4 }
-
-        Returns:
-                tuple: Response containing tokens and HTTP response code.
+        **Return Codes:**
+        ```
+        200 (OK): On success.
+        401 (Unauthroized): When username or password are incorrect.
+        422 (Unprocessable Entitiy): When the username or password can't be parsed.
+        ```
+        **Example:**
+        ```
+        curl -X POST
+            -H "Content-Type: application/json" 
+            -d '{"username": "bob", "password": "super_secret"}'
+        
+        { "access_token": fjr09hfp09h932jp9ruj3.3r8ihf8h0w8hr08ifhj804h8i.8h48ith08ity409hip0t4 }
+        ```
+        **Returns:**
+        ```
+        tuple: Response containing tokens and HTTP response code.
+        ```
         """
         if not request.is_json:
             return ({ "message": "JSON missing from request body"}, 422)
@@ -162,34 +166,41 @@ class Item(Resource):
     def get(self, queue: str, number: int) -> tuple:
         """Returns the JSON representation of the item requested.
 
-        Return Codes:
-                200 (OK): On success.
-
-        Example:
-            /api/ce/100 returns:
-            {
-                "lastUpdated": "07-23-20 10:11 PM",
-                "headers": [...],
-                "content": [...],
-                "isLocked": "ce 100 is locked by knewell using qvi",
-                "userEmail": "campb303@purdue.edu",
-                "userName": "Justin Campbell",
-                "userAlias": "campb303",
-                "assignedTo": "campb303",
-                "subject": "Beepboop",
-                "status": "Dont Delete",
-                "priority": "",
-                "deparment": "",
-                "building": "",
-                "dateReceived": "Tue, 23 Jun 2020 13:25:51 -0400"
-            }
-
-        Args:
-            queue (str): The queue of the item requested.
-            item (int): The number of the item requested.
-
-        Returns:
-            tuple: Item as JSON and HTTP response code.
+        **Return Codes:**
+        ```
+        200 (OK): On success.
+        ```
+
+        **Example:**
+        ```
+        /api/ce/100 returns:
+        {
+            "lastUpdated": "07-23-20 10:11 PM",
+            "headers": [...],
+            "content": [...],
+            "isLocked": "ce 100 is locked by knewell using qvi",
+            "userEmail": "campb303@purdue.edu",
+            "userName": "Justin Campbell",
+            "userAlias": "campb303",
+            "assignedTo": "campb303",
+            "subject": "Beepboop",
+            "status": "Dont Delete",
+            "priority": "",
+            "deparment": "",
+            "building": "",
+            "dateReceived": "Tue, 23 Jun 2020 13:25:51 -0400"
+        }
+        ```
+        **Args:**
+        ```
+        queue (str): The queue of the item requested.
+        item (int): The number of the item requested.
+        ```
+
+        **Returns:**
+        ```
+        tuple: Item as JSON and HTTP response code.
+        ```
         """
         return (ECNQueue.Item(queue, number).toJson(), 200)
 
@@ -198,14 +209,20 @@ class Queue(Resource):
     def get(self, queues: str) -> tuple:
         """Returns the JSON representation of the queue requested.
 
-        Return Codes:
-                200 (OK): On success.
+        **Return Codes:**
+        ```
+        200 (OK): On success.
+        ```
 
-        Args:
-            queues (str): Plus (+) deliminited list of queues.
+        **Args:**
+        ```
+        queues (str): Plus (+) deliminited list of queues.
+        ```
 
-        Returns:
-            tuple: Queues as JSON and HTTP response code.
+        **Returns:**
+        ```
+        tuple: Queues as JSON and HTTP response code.
+        ```
         """
         queues_requested = queues.split("+")
 
@@ -220,23 +237,28 @@ class QueueList(Resource):
     def get(self) -> tuple:
         """Returns a list of dictionaries with the number of items in each queue.
 
-        Return Codes:
-                200 (OK): On success.
-
-        Example:
-                [
-                    {
-                        name: "me",
-                        number_of_items: 42
-                    },
-                    {
-                        name: "bidc",
-                        number_of_items: 3
-                    }
-                ]
-
-        Returns:
-                tuple: Queues and item counts as JSON and HTTP response code.
+        **Return Codes:**
+        ```
+        200 (OK): On success.
+        ```
+
+        **Example:**
+        ```
+        [
+            {
+                name: "me",
+                number_of_items: 42
+            },
+            {
+                name: "bidc",
+                number_of_items: 3
+            }
+        ]
+        ```
+        **Returns:**
+        ```
+        tuple: Queues and item counts as JSON and HTTP response code.
+        ```
         """
         return (ECNQueue.getQueueCounts(), 200)