Added JSDoc for src/*

Signed-off-by: Matthew Nickson <mnickson@sidingsmedia.com>

src/util-frontend.js

@@ -26,8 +26,8 @@ function getTimezoneOffset(timeZone) {
 
 /**
 * Returns a list of timezones sorted by their offset from UTC.
-* @param {Array} timezones - An array of timezone objects.
+* @param {Object[]} timezones An array of timezone objects.
-* @returns {Array} A list of the given timezones sorted by their offset from UTC.
+* @returns {Object[]} A list of the given timezones sorted by their offset from UTC.
 *
 * Generated by Trelent
 */
@@ -63,6 +63,7 @@ export function timezoneList() {
     return result;
 }
 
+/** Set the locale of the HTML page */
 export function setPageLocale() {
     const html = document.documentElement;
     html.setAttribute("lang", currentLocale() );
@@ -70,7 +71,9 @@ export function setPageLocale() {
 }
 
 /**
+ * Get the base URL
  * Mainly used for dev, because the backend and the frontend are in different ports.
+ * @returns {string}
  */
 export function getResBaseURL() {
     const env = process.env.NODE_ENV;

src/util.js

@@ -18,6 +18,7 @@ exports.PENDING = 2;
 exports.STATUS_PAGE_ALL_DOWN = 0;
 exports.STATUS_PAGE_ALL_UP = 1;
 exports.STATUS_PAGE_PARTIAL_DOWN = 2;
+/** Flip the status of s */
 function flipStatus(s) {
     if (s === exports.UP) {
         return exports.DOWN;
@@ -28,6 +29,10 @@ function flipStatus(s) {
     return s;
 }
 exports.flipStatus = flipStatus;
+/**
+ * Delays for specified number of seconds
+ * @param ms Number of milliseconds to sleep for
+ */
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -83,6 +88,12 @@ class Logger {
             this.debug("server", this.hideLog);
         }
     }
+    /**
+     * Write a message to the log
+     * @param module The module the log comes from
+     * @param msg Message to write
+     * @param level Log level. One of INFO, WARN, ERROR, DEBUG or can be customized.
+     */
     log(module, msg, level) {
         if (this.hideLog[level] && this.hideLog[level].includes(module)) {
             return;
@@ -109,18 +120,44 @@ class Logger {
             console.log(formattedMessage);
         }
     }
+    /**
+     * Log an INFO message
+     * @param module Module log comes from
+     * @param msg Message to write
+     */
     info(module, msg) {
         this.log(module, msg, "info");
     }
+    /**
+     * Log a WARN message
+     * @param module Module log comes from
+     * @param msg Message to write
+     */
     warn(module, msg) {
         this.log(module, msg, "warn");
     }
+    /**
+     * Log an ERROR message
+     * @param module Module log comes from
+     * @param msg Message to write
+     */
     error(module, msg) {
         this.log(module, msg, "error");
     }
+    /**
+     * Log a DEBUG message
+     * @param module Module log comes from
+     * @param msg Message to write
+     */
     debug(module, msg) {
         this.log(module, msg, "debug");
     }
+    /**
+     * Log an exeption as an ERROR
+     * @param module Module log comes from
+     * @param exception The exeption to include
+     * @param msg The message to write
+     */
     exception(module, exception, msg) {
         let finalMessage = exception;
         if (msg) {
@@ -130,13 +167,13 @@ class Logger {
     }
 }
 exports.log = new Logger();
+/**
+ * String.prototype.replaceAll() polyfill
+ * https://gomakethings.com/how-to-replace-a-section-of-a-string-with-another-one-with-vanilla-js/
+ * @author Chris Ferdinandi
+ * @license MIT
+ */
 function polyfill() {
-    /**
-     * String.prototype.replaceAll() polyfill
-     * https://gomakethings.com/how-to-replace-a-section-of-a-string-with-another-one-with-vanilla-js/
-     * @author Chris Ferdinandi
-     * @license MIT
-     */
     if (!String.prototype.replaceAll) {
         String.prototype.replaceAll = function (str, newStr) {
             // If a regex pattern
@@ -153,6 +190,10 @@ class TimeLogger {
     constructor() {
         this.startTime = dayjs().valueOf();
     }
+    /**
+     * Output time since start of monitor
+     * @param name Name of monitor
+     */
     print(name) {
         if (exports.isDev && process.env.TIMELOGGER === "1") {
             console.log(name + ": " + (dayjs().valueOf() - this.startTime) + "ms");
@@ -201,6 +242,13 @@ let getRandomBytes = ((typeof window !== 'undefined' && window.crypto)
     : function () {
         return require("crypto").randomBytes;
     })();
+/**
+ * Get a random integer suitable for use in cryptography between upper
+ * and lower bounds.
+ * @param min Minimum value of integer
+ * @param max Maximum value of integer
+ * @returns Cryptographically suitable random integer
+ */
 function getCryptoRandomInt(min, max) {
     // synchronous version of: https://github.com/joepie91/node-random-number-csprng
     const range = max - min;
@@ -231,6 +279,11 @@ function getCryptoRandomInt(min, max) {
     }
 }
 exports.getCryptoRandomInt = getCryptoRandomInt;
+/**
+ * Generate a secret
+ * @param length Lenght of secret to generate
+ * @returns
+ */
 function genSecret(length = 64) {
     let secret = "";
     const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
@@ -241,6 +294,11 @@ function genSecret(length = 64) {
     return secret;
 }
 exports.genSecret = genSecret;
+/**
+ * Get the path of a monitor
+ * @param id ID of monitor
+ * @returns Formatted relative path
+ */
 function getMonitorRelativeURL(id) {
     return "/dashboard/" + id;
 }

src/util.ts

@@ -19,7 +19,7 @@ export const STATUS_PAGE_ALL_DOWN = 0;
 export const STATUS_PAGE_ALL_UP = 1;
 export const STATUS_PAGE_PARTIAL_DOWN = 2;
 
-
+/** Flip the status of s */
 export function flipStatus(s: number) {
     if (s === UP) {
         return DOWN;
@@ -32,6 +32,10 @@ export function flipStatus(s: number) {
     return s;
 }
 
+/**
+ * Delays for specified number of seconds
+ * @param ms Number of milliseconds to sleep for
+ */
 export function sleep(ms: number) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -94,6 +98,12 @@ class Logger {
         }
     }
 
+    /**
+     * Write a message to the log
+     * @param module The module the log comes from
+     * @param msg Message to write
+     * @param level Log level. One of INFO, WARN, ERROR, DEBUG or can be customized.
+     */
     log(module: string, msg: any, level: string) {
         if (this.hideLog[level] && this.hideLog[level].includes(module)) {
             return;
@@ -120,22 +130,48 @@ class Logger {
         }
     }
 
+    /**
+     * Log an INFO message
+     * @param module Module log comes from
+     * @param msg Message to write
+     */
     info(module: string, msg: any) {
         this.log(module, msg, "info");
     }
 
+    /**
+     * Log a WARN message
+     * @param module Module log comes from
+     * @param msg Message to write
+     */
     warn(module: string, msg: any) {
         this.log(module, msg, "warn");
     }
 
-   error(module: string, msg: any) {
+    /**
+     * Log an ERROR message
+     * @param module Module log comes from
+     * @param msg Message to write
+     */
+    error(module: string, msg: any) {
        this.log(module, msg, "error");
     }
 
-   debug(module: string, msg: any) {
+    /**
+     * Log a DEBUG message
+     * @param module Module log comes from
+     * @param msg Message to write
+     */
+    debug(module: string, msg: any) {
        this.log(module, msg, "debug");
     }
 
+    /**
+     * Log an exeption as an ERROR
+     * @param module Module log comes from
+     * @param exception The exeption to include
+     * @param msg The message to write
+     */
     exception(module: string, exception: any, msg: any) {
         let finalMessage = exception
 
@@ -151,13 +187,13 @@ export const log = new Logger();
 
 declare global { interface String { replaceAll(str: string, newStr: string): string; } }
 
+/**
+ * String.prototype.replaceAll() polyfill
+ * https://gomakethings.com/how-to-replace-a-section-of-a-string-with-another-one-with-vanilla-js/
+ * @author Chris Ferdinandi
+ * @license MIT
+ */
 export function polyfill() {
-    /**
-     * String.prototype.replaceAll() polyfill
-     * https://gomakethings.com/how-to-replace-a-section-of-a-string-with-another-one-with-vanilla-js/
-     * @author Chris Ferdinandi
-     * @license MIT
-     */
     if (!String.prototype.replaceAll) {
         String.prototype.replaceAll = function (str: string, newStr: string) {
             // If a regex pattern
@@ -177,7 +213,10 @@ export class TimeLogger {
     constructor() {
         this.startTime = dayjs().valueOf();
     }
-
+    /**
+     * Output time since start of monitor
+     * @param name Name of monitor
+     */
     print(name: string) {
         if (isDev && process.env.TIMELOGGER === "1") {
             console.log(name + ": " + (dayjs().valueOf() - this.startTime) + "ms")
@@ -231,6 +270,13 @@ let getRandomBytes = (
         }
 )();
 
+/**
+ * Get a random integer suitable for use in cryptography between upper
+ * and lower bounds.
+ * @param min Minimum value of integer
+ * @param max Maximum value of integer
+ * @returns Cryptographically suitable random integer
+ */
 export function getCryptoRandomInt(min: number, max: number):number {
 
     // synchronous version of: https://github.com/joepie91/node-random-number-csprng
@@ -267,6 +313,11 @@ export function getCryptoRandomInt(min: number, max: number):number {
     }
 }
 
+/**
+ * Generate a secret
+ * @param length Lenght of secret to generate
+ * @returns 
+ */
 export function genSecret(length = 64) {
     let secret = "";
     const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
@@ -277,6 +328,11 @@ export function genSecret(length = 64) {
     return secret;
 }
 
+/**
+ * Get the path of a monitor
+ * @param id ID of monitor
+ * @returns Formatted relative path
+ */
 export function getMonitorRelativeURL(id: string) {
     return "/dashboard/" + id;
 }