Add and improve documentation

Author: scinorandex

src/api/errorHandler.ts

@@ -1,5 +1,10 @@
 import { ErrorRequestHandler } from "express";
 
+/**
+ *
+ * @param error Error object, received from errors thrown in the code
+ * @param res Response object from Express
+ */
 export const errorHandler: ErrorRequestHandler = (error, _, res, _next) => {
     const statusCode = res.statusCode === 200 ? 500 : res.statusCode;
     res.status(statusCode);

src/api/handleAsync.ts

@@ -1,5 +1,11 @@
 import { Request, Response, NextFunction } from "express";
 type Handler<R> = (req: Request, res: Response, next: NextFunction) => R;
+
+/**
+ * @example router.use("/path/", handleAsync((req, res, next)=>{res.send("Hello World!")}));
+ * @param asyncFn An asyncronous function that takes in req, res, and next
+ * @returns An asyncronous function where errors will be catched and sent to the error handler
+ */
 const handleAsync: (asyncFn: Handler<Promise<void>>) => Handler<void> = (
     asyncFn
 ) => {

src/api/plainRouter.ts

@@ -8,6 +8,10 @@ import {
 } from "../utils/plainHandlers";
 import { isQuiet } from "./router";
 
+/**
+ * The plainRouter handles all the plain routes such as /basic, /cmd, and /plain
+ * It also handles the quiet version of these routes
+ */
 export const plainRouter = Router({ mergeParams: true });
 
 plainRouter.get(

src/api/userAgent.ts

@@ -1,4 +1,5 @@
 import { Request, Response, NextFunction } from "express";
+const { version } = require("../../package.json");
 
 // Type of middleware and handler
 export type Handler = (
@@ -7,17 +8,28 @@ export type Handler = (
     next: NextFunction
 ) => Promise<void> | void;
 
+/**
+ *
+ * @param userAgent The user agent of the requester
+ * @returns A boolean that is true of the user agent provided is from curl / wget / httpie
+ */
 const isTerminal: (userAgent: string | undefined) => boolean = (userAgent) => {
     if (userAgent === undefined) return false;
     if (/curl|wget|httpie/i.test(userAgent)) return true;
     return false;
 };
 
 export const userAgentMiddleware: Handler = (req, res, next) => {
+    /**
+     * Get the user agent from the request
+     * Determine if the user agent is from curl / wget / httpie
+     * If true then proceed using the next function
+     * Else return with message
+     */
     const userAgent = req.headers["user-agent"];
     if (!isTerminal(userAgent)) {
         res.send(
-            `Welcome to COVID-19 Tracker CLI v3.9.3 by Waren Gonzaga.\n\nPlease visit: https://warengonza.ga/covid19-tracker-cli`
+            `Welcome to COVID-19 Tracker CLI v${version} by Waren Gonzaga with Wareneutron Developers\nPlease visit: https://warengonza.ga/covid19-tracker-cli\n`
         );
         return;
     }

src/utils/generatePlainOutput.ts

@@ -3,6 +3,13 @@ import { getSaying } from "./getSaying";
 import { getTimestamp } from "./getTimestamp";
 const { version } = require("../../package.json");
 
+/**
+ * @param info The plain data that will be shown at the top in two columns
+ * @param chartType The type of chart that will be shown. Ex:  "Global Update", "Philippine Historical Chart"
+ * @param quiet Boolean, set to true if the user requsted quiet mode
+ * @param extraRows Any extra rows that will be presented under the main info. Used for Asciichart
+ * @returns A string showing the provided data and configuration
+ */
 export const generatePlainOutput: (
     info: PlainData,
     chartType: string,
@@ -45,9 +52,7 @@ export const generatePlainOutput: (
     }
 
     // responseArray is the array of the raw data **before** adding the separator lines
-
     let responseArray: string[] = [timestamp, table];
-
     if (!quiet) responseArray.unshift(header);
 
     // Add extraRows to responseArray

src/utils/generateTable.ts

@@ -176,7 +176,7 @@ const separatorHandler: (
         );
     }
 
-    return "If you have reached this then something has gone wrong";
+    throw new Error("Separator handler conditions failed");
 };
 
 /**

src/utils/getInformation.ts

@@ -62,7 +62,7 @@ export const getAllInfo: (
  * @param country the country code or string that the user provides from req.params or CLI
  * @param isPlain Set to true to recieve an object containing the responses instead of the rows
  * @returns an object containing the data and metainfo **if isPlain is set to true**
- * @returns an array in the format of [timestamp, API countryname, formal countryname, rows[]] **if isPlain is false
+ * @returns an array in the format of [timestamp, API countryname, formal countryname, rows[]] **if isPlain is false**
  */
 export const getCountryInfo: (
     country: string,

src/utils/getSaying.ts

@@ -33,6 +33,9 @@ const sayings = [
     "Wine is the most healthful and most hygienic of beverages - Louis Pasteur",
 ];
 
+/**
+ * @returns A random saying from the array of sayings
+ */
 export const getSaying: () => string = () => {
     const index = Math.floor(Math.random() * sayings.length);
     return sayings[index];

src/utils/getTimestamp.ts

@@ -1,5 +1,4 @@
 /**
- *
  * @param timestamp Timestamp in Epoch Time
  * @returns String in form of As of MM/DD/YYYY, HH:mm:SS AM/PM [Date: MM/DD/YYYY]
  */