From f55350bebc13035e8ca54a54d84e7d8c40aec2a0 Mon Sep 17 00:00:00 2001
From: Calum Bird <calum@trelent.net>
Date: Tue, 9 Nov 2021 21:24:31 -0800
Subject: [PATCH] Generated documentation :)

---
 extra/download-dist.js              |  6 +++
 extra/update-version.js             | 19 ++++++++
 server/auth.js                      |  7 +++
 server/client.js                    | 12 +++++
 server/image-data-uri.js            | 20 +++++++++
 server/modules/apicache/apicache.js | 70 +++++++++++++++++++++++++++++
 server/notification.js              |  7 +++
 server/ping-lite.js                 | 12 +++++
 server/server.js                    | 53 ++++++++++++++++++++++
 src/util-frontend.js                | 15 ++++++-
 src/util.js                         | 14 ++++++
 11 files changed, 234 insertions(+), 1 deletion(-)

diff --git a/extra/download-dist.js b/extra/download-dist.js
index dc64166c4..a9c630239 100644
--- a/extra/download-dist.js
+++ b/extra/download-dist.js
@@ -11,6 +11,12 @@ const filename = "dist.tar.gz";
 const url = `https://github.com/louislam/uptime-kuma/releases/download/${version}/${filename}`;
 download(url);
 
+/**
+ * Downloads the latest version of the dist from a GitHub release.
+ * @param {string} url The URL to download from.
+ *
+ * Generated by Trelent
+ */
 function download(url) {
     console.log(url);
 
diff --git a/extra/update-version.js b/extra/update-version.js
index 2e3b42da8..34b46281f 100644
--- a/extra/update-version.js
+++ b/extra/update-version.js
@@ -37,6 +37,12 @@ if (! exists) {
     console.log("version exists");
 }
 
+/**
+ * Updates the version number in package.json and commits it to git
+ * @param {string} version - The new version number
+ *
+ * Generated by Trelent
+ */
 function commit(version) {
     let msg = "update to " + version;
 
@@ -54,6 +60,12 @@ function tag(version) {
     console.log(res.stdout.toString().trim());
 }
 
+/**
+ * Checks if a given version is already tagged in the git repository.
+ * @param {string} version - The version to check for.
+ *
+ * Generated by Trelent
+ */
 function tagExists(version) {
     if (! version) {
         throw new Error("invalid version");
@@ -64,6 +76,13 @@ function tagExists(version) {
     return res.stdout.toString().trim() === version;
 }
 
+/**
+ * Update the How-to-Update.md file in the wiki to reflect a new version of Kuma.
+ * @param {string} oldVersion The previous version of Kuma that was released.
+ * @param {string} newVersion The current version of Kuma that is being released.
+ *
+ * Generated by Trelent
+ */
 function updateWiki(oldVersion, newVersion) {
     const wikiDir = "./tmp/wiki";
     const howToUpdateFilename = "./tmp/wiki/🆙-How-to-Update.md";
diff --git a/server/auth.js b/server/auth.js
index c476ea1e3..2cb71e93c 100644
--- a/server/auth.js
+++ b/server/auth.js
@@ -30,6 +30,13 @@ exports.login = async function (username, password) {
     return null;
 };
 
+/**
+ * A function that checks if a user is logged in.
+ * @param {string} username The username of the user to check for.
+ * @param {function} callback The callback to call when done, with an error and result parameter.
+ *
+ * Generated by Trelent
+ */
 function myAuthorizer(username, password, callback) {
     setting("disableAuth").then((result) => {
         if (result) {
diff --git a/server/client.js b/server/client.js
index c7b3bc162..04a6abcd8 100644
--- a/server/client.js
+++ b/server/client.js
@@ -7,6 +7,12 @@ const { io } = require("./server");
 const { setting } = require("./util-server");
 const checkVersion = require("./check-version");
 
+/**
+ * Send a list of notifications to the user.
+ * @param {Socket} socket The socket object that is connected to the client.
+ *
+ * Generated by Trelent
+ */
 async function sendNotificationList(socket) {
     const timeLogger = new TimeLogger();
 
@@ -83,6 +89,12 @@ async function sendImportantHeartbeatList(socket, monitorID, toUser = false, ove
 
 }
 
+/**
+ * Emits the version information to the client.
+ * @param {Socket} socket The socket object that is connected to the client.
+ *
+ * Generated by Trelent
+ */
 async function sendInfo(socket) {
     socket.emit("info", {
         version: checkVersion.version,
diff --git a/server/image-data-uri.js b/server/image-data-uri.js
index 3ccaab7d5..1ab499c15 100644
--- a/server/image-data-uri.js
+++ b/server/image-data-uri.js
@@ -6,6 +6,12 @@ let fs = require("fs");
 
 let ImageDataURI = (() => {
 
+    /**
+     * @param {string} dataURI - A string that is a valid Data URI.
+     * @returns {?Object} An object with properties "imageType" and "dataBase64". The former is the image type, e.g., "png", and the latter is a base64 encoded string of the image's binary data. If it fails to parse, returns null instead of an object.
+     *
+     * Generated by Trelent
+     */
     function decode(dataURI) {
         if (!/data:image\//.test(dataURI)) {
             console.log("ImageDataURI :: Error :: It seems that it is not an Image Data URI. Couldn't match \"data:image/\"");
@@ -20,6 +26,13 @@ let ImageDataURI = (() => {
         };
     }
 
+    /**
+     * @param {Buffer} data - The image data to be encoded.
+     * @param {String} mediaType - The type of the image, e.g., "image/png".
+     * @returns {String|null} A string representing the base64-encoded version of the given Buffer object or null if an error occurred.
+     *
+     * Generated by Trelent
+     */
     function encode(data, mediaType) {
         if (!data || !mediaType) {
             console.log("ImageDataURI :: Error :: Missing some of the required params: data, mediaType ");
@@ -33,6 +46,13 @@ let ImageDataURI = (() => {
         return dataImgBase64;
     }
 
+    /**
+     * Converts a data URI to a file path.
+     * @param {string} dataURI The Data URI of the image.
+     * @param {string} [filePath] The path where the image will be saved, defaults to "./".
+     *
+     * Generated by Trelent
+     */
     function outputFile(dataURI, filePath) {
         filePath = filePath || "./";
         return new Promise((resolve, reject) => {
diff --git a/server/modules/apicache/apicache.js b/server/modules/apicache/apicache.js
index 22d1fed71..25f0a54f5 100644
--- a/server/modules/apicache/apicache.js
+++ b/server/modules/apicache/apicache.js
@@ -68,6 +68,15 @@ function ApiCache() {
     instances.push(this);
     this.id = instances.length;
 
+    /**
+     * Logs a message to the console if the `DEBUG` environment variable is set.
+     * @param {string} a - The first argument to log.
+     * @param {string} b - The second argument to log.
+     * @param {string} c - The third argument to log.
+     * @param {string} d - The fourth argument to log, and so on... (optional)
+     *
+     * Generated by Trelent
+     */
     function debug(a, b, c, d) {
         let arr = ["\x1b[36m[apicache]\x1b[0m", a, b, c, d].filter(function (arg) {
             return arg !== undefined;
@@ -77,6 +86,13 @@ function ApiCache() {
         return (globalOptions.debug || debugEnv) && console.log.apply(null, arr);
     }
 
+    /**
+     * Returns true if the given request and response should be logged.
+     * @param {Object} request The HTTP request object.
+     * @param {Object} response The HTTP response object.
+     *
+     * Generated by Trelent
+     */
     function shouldCacheResponse(request, response, toggle) {
         let opt = globalOptions;
         let codes = opt.statusCodes;
@@ -99,6 +115,12 @@ function ApiCache() {
         return true;
     }
 
+    /**
+     * Adds a key to the index.
+     * @param {string} key The key to add.
+     *
+     * Generated by Trelent
+     */
     function addIndexEntries(key, req) {
         let groupName = req.apicacheGroup;
 
@@ -111,6 +133,13 @@ function ApiCache() {
         index.all.unshift(key);
     }
 
+    /**
+     * Returns a new object containing only the whitelisted headers.
+     * @param {Object} headers The original object of header names and values.
+     * @param {Array.<string>} globalOptions.headerWhitelist An array of strings representing the whitelisted header names to keep in the output object.
+     *
+     * Generated by Trelent
+     */
     function filterBlacklistedHeaders(headers) {
         return Object.keys(headers)
             .filter(function (key) {
@@ -122,6 +151,12 @@ function ApiCache() {
             }, {});
     }
 
+    /**
+     * @param {Object} headers The response headers to filter.
+     * @returns {Object} A new object containing only the whitelisted response headers.
+     *
+     * Generated by Trelent
+     */
     function createCacheObject(status, headers, data, encoding) {
         return {
             status: status,
@@ -132,6 +167,14 @@ function ApiCache() {
         };
     }
 
+    /**
+     * Sets a cache value for the given key.
+     * @param {string} key The cache key to set.
+     * @param {*} value The cache value to set.
+     * @param {number} duration How long in milliseconds the cached response should be valid for (defaults to 1 hour).
+     *
+     * Generated by Trelent
+     */
     function cacheResponse(key, value, duration) {
         let redis = globalOptions.redisClient;
         let expireCallback = globalOptions.events.expire;
@@ -154,6 +197,12 @@ function ApiCache() {
         }, Math.min(duration, 2147483647));
     }
 
+    /**
+     * Appends content to the response.
+     * @param {string|Buffer} content The content to append.
+     *
+     * Generated by Trelent
+     */
     function accumulateContent(res, content) {
         if (content) {
             if (typeof content == "string") {
@@ -179,6 +228,13 @@ function ApiCache() {
         }
     }
 
+    /**
+     * Monkeypatches the response object to add cache control headers and create a cache object.
+     * @param {Object} req - The request object.
+     * @param {Object} res - The response object.
+     *
+     * Generated by Trelent
+     */
     function makeResponseCacheable(req, res, next, key, duration, strDuration, toggle) {
     // monkeypatch res.end to create cache object
         res._apicache = {
@@ -245,6 +301,13 @@ function ApiCache() {
         next();
     }
 
+    /**
+     * @param {Request} request
+     * @param {Response} response
+     * @returns {boolean|undefined} true if the request should be cached, false otherwise. If undefined, defaults to true.
+     *
+     * Generated by Trelent
+     */
     function sendCachedResponse(request, response, cacheObject, toggle, next, duration) {
         if (toggle && !toggle(request, response)) {
             return next();
@@ -365,6 +428,13 @@ function ApiCache() {
         return this.getIndex();
     };
 
+    /**
+     * Converts a duration string to an integer number of milliseconds.
+     * @param {string} duration - The string to convert.
+     * @returns {number} The converted value in milliseconds, or the defaultDuration if it can't be parsed.
+     *
+     * Generated by Trelent
+     */
     function parseDuration(duration, defaultDuration) {
         if (typeof duration === "number") {
             return duration;
diff --git a/server/notification.js b/server/notification.js
index 18c823b2b..136c95532 100644
--- a/server/notification.js
+++ b/server/notification.js
@@ -140,6 +140,13 @@ class Notification {
 
 }
 
+/**
+ * Adds a new monitor to the database.
+ * @param {number} userID The ID of the user that owns this monitor.
+ * @param {string} name The name of this monitor.
+ *
+ * Generated by Trelent
+ */
 async function applyNotificationEveryMonitor(notificationID, userID) {
     let monitors = await R.getAll("SELECT id FROM monitor WHERE user_id = ?", [
         userID
diff --git a/server/ping-lite.js b/server/ping-lite.js
index b2d6405ad..ea3f67ed7 100644
--- a/server/ping-lite.js
+++ b/server/ping-lite.js
@@ -8,6 +8,13 @@ const util = require("./util-server");
 
 module.exports = Ping;
 
+/**
+ * @param {string} host - The host to ping
+ * @param {object} [options] - Options for the ping command
+ * @param {array|string} [options.args] - Arguments to pass to the ping command
+ *
+ * Generated by Trelent
+ */
 function Ping(host, options) {
     if (!host) {
         throw new Error("You must specify a host to ping!");
@@ -125,6 +132,11 @@ Ping.prototype.send = function (callback) {
         }
     });
 
+    /**
+     * @param {Function} callback
+     *
+     * Generated by Trelent
+     */
     function onEnd() {
         let stdout = this.stdout._stdout;
         let stderr = this.stderr._stderr;
diff --git a/server/server.js b/server/server.js
index d1fd7ff29..536d0926c 100644
--- a/server/server.js
+++ b/server/server.js
@@ -1349,6 +1349,13 @@ exports.entryPage = "dashboard";
 
 })();
 
+/**
+ * Adds or removes notifications from a monitor.
+ * @param {number} monitorID The ID of the monitor to add/remove notifications from.
+ * @param {Array.<number>} notificationIDList An array of IDs for the notifications to add/remove.
+ *
+ * Generated by Trelent
+ */
 async function updateMonitorNotification(monitorID, notificationIDList) {
     await R.exec("DELETE FROM monitor_notification WHERE monitor_id = ? ", [
         monitorID,
@@ -1364,6 +1371,13 @@ async function updateMonitorNotification(monitorID, notificationIDList) {
     }
 }
 
+/**
+ * This function checks if the user owns a monitor with the given ID.
+ * @param {number} monitorID - The ID of the monitor to check ownership for.
+ * @param {number} userID - The ID of the user who is trying to access this data.
+ *
+ * Generated by Trelent
+ */
 async function checkOwner(userID, monitorID) {
     let row = await R.getRow("SELECT id FROM monitor WHERE id = ? AND user_id = ? ", [
         monitorID,
@@ -1381,6 +1395,13 @@ async function sendMonitorList(socket) {
     return list;
 }
 
+/**
+ * This function is used to send the heartbeat list of a monitor.
+ * @param {Socket} socket - The socket object that will be used to send the data.
+ * @param {String} monitorID - The ID of the monitor that will have its heartbeat list sent.
+ *
+ * Generated by Trelent
+ */
 async function afterLogin(socket, user) {
     socket.userID = user.id;
     socket.join(user.id);
@@ -1403,6 +1424,13 @@ async function afterLogin(socket, user) {
     }
 }
 
+/**
+ * Get a list of monitors for the given user.
+ * @param {string} userID - The ID of the user to get monitors for.
+ * @returns {Promise<Object>} A promise that resolves to an object with monitor IDs as keys and monitor objects as values.
+ *
+ * Generated by Trelent
+ */
 async function getMonitorJSONList(userID) {
     let result = {};
 
@@ -1417,6 +1445,11 @@ async function getMonitorJSONList(userID) {
     return result;
 }
 
+/**
+ * Connect to the database and patch it if necessary.
+ *
+ * Generated by Trelent
+ */
 async function initDatabase() {
     if (! fs.existsSync(Database.path)) {
         console.log("Copying Database");
@@ -1451,6 +1484,13 @@ async function initDatabase() {
     jwtSecret = jwtSecretBean.value;
 }
 
+/**
+ * Resume a monitor.
+ * @param {string} userID - The ID of the user who owns the monitor.
+ * @param {string} monitorID - The ID of the monitor to resume.
+ *
+ * Generated by Trelent
+ */
 async function startMonitor(userID, monitorID) {
     await checkOwner(userID, monitorID);
 
@@ -1477,6 +1517,13 @@ async function restartMonitor(userID, monitorID) {
     return await startMonitor(userID, monitorID);
 }
 
+/**
+ * Pause a monitor.
+ * @param {string} userID - The ID of the user who owns the monitor.
+ * @param {string} monitorID - The ID of the monitor to pause.
+ *
+ * Generated by Trelent
+ */
 async function pauseMonitor(userID, monitorID) {
     await checkOwner(userID, monitorID);
 
@@ -1509,6 +1556,12 @@ async function startMonitors() {
     }
 }
 
+/**
+ * Stops all monitors and closes the database connection.
+ * @param {string} signal The signal that triggered this function to be called.
+ *
+ * Generated by Trelent
+ */
 async function shutdownFunction(signal) {
     console.log("Shutdown requested");
     console.log("Called signal: " + signal);
diff --git a/src/util-frontend.js b/src/util-frontend.js
index 9094dda43..dff6d679b 100644
--- a/src/util-frontend.js
+++ b/src/util-frontend.js
@@ -7,6 +7,12 @@ import { localeDirection, currentLocale } from "./i18n";
 dayjs.extend(utc);
 dayjs.extend(timezone);
 
+/**
+ * Returns the offset from UTC in hours for the current locale.
+ * @returns {number} The offset from UTC in hours.
+ *
+ * Generated by Trelent
+ */
 function getTimezoneOffset(timeZone) {
     const now = new Date();
     const tzString = now.toLocaleString("en-US", {
@@ -18,7 +24,14 @@ function getTimezoneOffset(timeZone) {
     return -offset;
 }
 
-export function timezoneList() {
+export /**
+ * Returns a list of timezones sorted by their offset from UTC.
+ * @param {Array} timezones - An array of timezone objects.
+ * @returns {Array} A list of the given timezones sorted by their offset from UTC.
+ *
+ * Generated by Trelent
+ */
+function timezoneList() {
     let result = [];
 
     for (let timezone of timezones) {
diff --git a/src/util.js b/src/util.js
index b2df7ac79..9945d7cfb 100644
--- a/src/util.js
+++ b/src/util.js
@@ -121,6 +121,13 @@ let getRandomBytes = ((typeof window !== 'undefined' && window.crypto)
     : function () {
         return require("crypto").randomBytes;
     })();
+/**
+ * Returns a random integer between min (inclusive) and max (exclusive).
+ * @param {number} min The minimum value.
+ * @param {number} max The maximum value.
+ *
+ * Generated by Trelent
+ */
 function getCryptoRandomInt(min, max) {
     // synchronous version of: https://github.com/joepie91/node-random-number-csprng
     const range = max - min;
@@ -151,6 +158,13 @@ function getCryptoRandomInt(min, max) {
     }
 }
 exports.getCryptoRandomInt = getCryptoRandomInt;
+/**
+ * Generates a random string of length `length` from the characters in `chars`.
+ * @param {number} length The number of characters to generate.
+ * @param {string} chars A string containing all the possible characters to use for generating the random string.
+ *
+ * Generated by Trelent
+ */
 function genSecret(length = 64) {
     let secret = "";
     const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";