Merge pull request #2549 from Computroniks/docs/update-jsdoc-2023-01-05

Added missing JSDoc comments

extra/beta/update-version.js

@@ -32,6 +32,10 @@ if (! exists) {
     process.exit(1);
 }
 
+/**
+ * Commit updated files
+ * @param {string} version Version to update to
+ */
 function commit(version) {
     let msg = "Update to " + version;
 
@@ -47,6 +51,10 @@ function commit(version) {
     console.log(res.stdout.toString().trim());
 }
 
+/**
+ * Create a tag with the specified version
+ * @param {string} version Tag to create
+ */
 function tag(version) {
     let res = childProcess.spawnSync("git", [ "tag", version ]);
     console.log(res.stdout.toString().trim());
@@ -55,6 +63,11 @@ function tag(version) {
     console.log(res.stdout.toString().trim());
 }
 
+/**
+ * Check if a tag exists for the specified version
+ * @param {string} version Version to check
+ * @returns {boolean} Does the tag already exist
+ */
 function tagExists(version) {
     if (! version) {
         throw new Error("invalid version");

extra/download-cloudflared.js

@@ -25,6 +25,10 @@ if (platform === "linux/amd64") {
 const file = fs.createWriteStream("cloudflared.deb");
 get("https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-" + arch + ".deb");
 
+/**
+ * Download specified file
+ * @param {string} url URL to request
+ */
 function get(url) {
     http.get(url, function (res) {
         if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {

extra/remove-2fa.js

@@ -43,6 +43,11 @@ const main = async () => {
     console.log("Finished.");
 };
 
+/**
+ * Ask question of user
+ * @param {string} question Question to ask
+ * @returns {Promise<string>} Users response
+ */
 function question(question) {
     return new Promise((resolve) => {
         rl.question(question, (answer) => {

extra/reset-password.js

@@ -53,6 +53,11 @@ const main = async () => {
     console.log("Finished.");
 };
 
+/**
+ * Ask question of user
+ * @param {string} question Question to ask
+ * @returns {Promise<string>} Users response
+ */
 function question(question) {
     return new Promise((resolve) => {
         rl.question(question, (answer) => {

extra/simple-dns-server.js

@@ -135,6 +135,11 @@ server.listen({
     udp: 5300
 });
 
+/**
+ * Get human readable request type from request code
+ * @param {number} code Request code to translate
+ * @returns {string} Human readable request type
+ */
 function type(code) {
     for (let name in Packet.TYPE) {
         if (Packet.TYPE[name] === code) {

extra/simple-mqtt-server.js

@@ -11,6 +11,7 @@ class SimpleMqttServer {
         this.port = port;
     }
 
+    /** Start the MQTT server */
     start() {
         this.server.listen(this.port, () => {
             console.log("server started and listening on port ", this.port);

extra/update-version.js

@@ -36,10 +36,8 @@ if (! exists) {
 }
 
 /**
- * Updates the version number in package.json and commits it to git.
- * @param {string} version - The new version number
- *
- * Generated by Trelent
+ * Commit updated files
+ * @param {string} version Version to update to
  */
 function commit(version) {
     let msg = "Update to " + version;
@@ -53,16 +51,19 @@ function commit(version) {
     }
 }
 
+/**
+ * Create a tag with the specified version
+ * @param {string} version Tag to create
+ */
 function tag(version) {
     let res = childProcess.spawnSync("git", [ "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
+ * Check if a tag exists for the specified version
+ * @param {string} version Version to check
+ * @returns {boolean} Does the tag already exist
  */
 function tagExists(version) {
     if (! version) {

extra/update-wiki-version.js

@@ -10,6 +10,10 @@ if (!newVersion) {
 
 updateWiki(newVersion);
 
+/**
+ * Update the wiki with new version number
+ * @param {string} newVersion Version to update to
+ */
 function updateWiki(newVersion) {
     const wikiDir = "./tmp/wiki";
     const howToUpdateFilename = "./tmp/wiki/🆙-How-to-Update.md";
@@ -39,6 +43,10 @@ function updateWiki(newVersion) {
     safeDelete(wikiDir);
 }
 
+/**
+ * Check if a directory exists and then delete it
+ * @param {string} dir Directory to delete
+ */
 function safeDelete(dir) {
     if (fs.existsSync(dir)) {
         fs.rm(dir, {

server/auth.js

@@ -63,6 +63,12 @@ function myAuthorizer(username, password, callback) {
     });
 }
 
+/**
+ * Use basic auth if auth is not disabled
+ * @param {express.Request} req Express request object
+ * @param {express.Response} res Express response object
+ * @param {express.NextFunction} next
+ */
 exports.basicAuth = async function (req, res, next) {
     const middleware = basicAuth({
         authorizer: myAuthorizer,

server/cacheable-dns-http-agent.js

@@ -37,6 +37,10 @@ class CacheableDnsHttpAgent {
         this.enable = isEnable;
     }
 
+    /**
+     * Attach cacheable to HTTP agent
+     * @param {http.Agent} agent Agent to install
+     */
     static install(agent) {
         this.cacheable.install(agent);
     }

server/jobs.js

@@ -32,6 +32,7 @@ const initBackgroundJobs = function (args) {
     return bree;
 };
 
+/** Stop all background jobs if running */
 const stopBackgroundJobs = function () {
     if (bree) {
         bree.stop();

server/model/maintenance.js

@@ -112,6 +112,11 @@ class Maintenance extends BeanModel {
         return this.toPublicJSON(timezone);
     }
 
+    /**
+     * Get a list of weekdays that the maintenance is active for
+     * Monday=1, Tuesday=2 etc.
+     * @returns {number[]} Array of active weekdays
+     */
     getDayOfWeekList() {
         log.debug("timeslot", "List: " + this.weekdays);
         return JSON.parse(this.weekdays).sort(function (a, b) {
@@ -119,12 +124,20 @@ class Maintenance extends BeanModel {
         });
     }
 
+    /**
+     * Get a list of days in month that maintenance is active for
+     * @returns {number[]} Array of active days in month
+     */
     getDayOfMonthList() {
         return JSON.parse(this.days_of_month).sort(function (a, b) {
             return a - b;
         });
     }
 
+    /**
+     * Get the start date and time for maintenance
+     * @returns {dayjs.Dayjs} Start date and time
+     */
     getStartDateTime() {
         let startOfTheDay = dayjs.utc(this.start_date).format("HH:mm");
         log.debug("timeslot", "startOfTheDay: " + startOfTheDay);
@@ -137,6 +150,10 @@ class Maintenance extends BeanModel {
         return dayjs.utc(this.start_date).add(startTimeSecond, "second");
     }
 
+    /**
+     * Get the duraction of maintenance in seconds
+     * @returns {number} Duration of maintenance
+     */
     getDuration() {
         let duration = dayjs.utc(this.end_time, "HH:mm").diff(dayjs.utc(this.start_time, "HH:mm"), "second");
         // Add 24hours if it is across day
@@ -146,6 +163,12 @@ class Maintenance extends BeanModel {
         return duration;
     }
 
+    /**
+     * Convert data from socket to bean
+     * @param {Bean} bean Bean to fill in
+     * @param {Object} obj Data to fill bean with
+     * @returns {Bean} Filled bean
+     */
     static jsonToBean(bean, obj) {
         if (obj.id) {
             bean.id = obj.id;

server/model/maintenance_timeslot.js

@@ -6,6 +6,11 @@ const { UptimeKumaServer } = require("../uptime-kuma-server");
 
 class MaintenanceTimeslot extends BeanModel {
 
+    /**
+     * Return an object that ready to parse to JSON for public
+     * Only show necessary data to public
+     * @returns {Object}
+     */
     async toPublicJSON() {
         const serverTimezoneOffset = UptimeKumaServer.getInstance().getTimezoneOffset();
 
@@ -21,6 +26,10 @@ class MaintenanceTimeslot extends BeanModel {
         return obj;
     }
 
+    /**
+     * Return an object that ready to parse to JSON
+     * @returns {Object}
+     */
     async toJSON() {
         return await this.toPublicJSON();
     }

server/model/monitor.js

@@ -748,6 +748,13 @@ class Monitor extends BeanModel {
         }
     }
 
+    /**
+     * Make a request using axios
+     * @param {Object} options Options for Axios
+     * @param {boolean} finalCall Should this be the final call i.e
+     * don't retry on faliure
+     * @returns {Object} Axios response
+     */
     async makeAxiosRequest(options, finalCall = false) {
         try {
             let res;
@@ -1229,6 +1236,7 @@ class Monitor extends BeanModel {
         return maintenance.count !== 0;
     }
 
+    /** Make sure monitor interval is between bounds */
     validate() {
         if (this.interval > MAX_INTERVAL_SECOND) {
             throw new Error(`Interval cannot be more than ${MAX_INTERVAL_SECOND} seconds`);

server/notification-providers/serverchan.js

@@ -21,6 +21,12 @@ class ServerChan extends NotificationProvider {
         }
     }
 
+    /**
+     * Get the formatted title for message
+     * @param {?Object} monitorJSON Monitor details (For Up/Down only)
+     * @param {?Object} heartbeatJSON Heartbeat details (For Up/Down only)
+     * @returns {string} Formatted title
+     */
     checkStatus(heartbeatJSON, monitorJSON) {
         let title = "UptimeKuma Message";
         if (heartbeatJSON != null && heartbeatJSON["status"] === UP) {

server/prometheus.js

@@ -99,6 +99,7 @@ class Prometheus {
         }
     }
 
+    /** Remove monitor from prometheus */
     remove() {
         try {
             monitorCertDaysRemaining.remove(this.monitorLabelValues);

server/uptime-cache-list.js

@@ -6,10 +6,10 @@ class UptimeCacheList {
     static list = {};
 
     /**
-     *
-     * @param monitorID
-     * @param duration
-     * @return number
+     * Get the uptime for a specific period
+     * @param {number} monitorID
+     * @param {number} duration
+     * @return {number}
      */
     static getUptime(monitorID, duration) {
         if (UptimeCacheList.list[monitorID] && UptimeCacheList.list[monitorID][duration]) {
@@ -20,6 +20,12 @@ class UptimeCacheList {
         }
     }
 
+    /**
+     * Add uptime for specified monitor
+     * @param {number} monitorID
+     * @param {number} duration
+     * @param {number} uptime Uptime to add
+     */
     static addUptime(monitorID, duration, uptime) {
         log.debug("UptimeCacheList", "addUptime: " + monitorID + " " + duration);
         if (!UptimeCacheList.list[monitorID]) {
@@ -28,6 +34,10 @@ class UptimeCacheList {
         UptimeCacheList.list[monitorID][duration] = uptime;
     }
 
+    /**
+     * Clear cache for specified monitor
+     * @param {number} monitorID
+     */
     static clearCache(monitorID) {
         log.debug("UptimeCacheList", "clearCache: " + monitorID);
         delete UptimeCacheList.list[monitorID];

server/uptime-kuma-server.js

@@ -86,6 +86,7 @@ class UptimeKumaServer {
         this.io = new Server(this.httpServer);
     }
 
+    /** Initialise app after the database has been set up */
     async initAfterDatabaseReady() {
         await CacheableDnsHttpAgent.update();
 
@@ -98,6 +99,11 @@ class UptimeKumaServer {
         this.generateMaintenanceTimeslotsInterval = setInterval(this.generateMaintenanceTimeslots, 60 * 1000);
     }
 
+    /**
+     * Send list of monitors to client
+     * @param {Socket} socket
+     * @returns {Object} List of monitors
+     */
     async sendMonitorList(socket) {
         let list = await this.getMonitorJSONList(socket.userID);
         this.io.to(socket.userID).emit("monitorList", list);
@@ -134,6 +140,11 @@ class UptimeKumaServer {
         return await this.sendMaintenanceListByUserID(socket.userID);
     }
 
+    /**
+     * Send list of maintenances to user
+     * @param {number} userID
+     * @returns {Object}
+     */
     async sendMaintenanceListByUserID(userID) {
         let list = await this.getMaintenanceJSONList(userID);
         this.io.to(userID).emit("maintenanceList", list);
@@ -185,6 +196,11 @@ class UptimeKumaServer {
         errorLogStream.end();
     }
 
+    /**
+     * Get the IP of the client connected to the socket
+     * @param {Socket} socket
+     * @returns {string}
+     */
     async getClientIP(socket) {
         let clientIP = socket.client.conn.remoteAddress;
 
@@ -203,6 +219,12 @@ class UptimeKumaServer {
         }
     }
 
+    /**
+     * Attempt to get the current server timezone
+     * If this fails, fall back to environment variables and then make a
+     * guess.
+     * @returns {string}
+     */
     async getTimezone() {
         let timezone = await Settings.get("serverTimezone");
         if (timezone) {
@@ -214,16 +236,25 @@ class UptimeKumaServer {
         }
     }
 
+    /**
+     * Get the current offset
+     * @returns {string}
+     */
     getTimezoneOffset() {
         return dayjs().format("Z");
     }
 
+    /**
+     * Set the current server timezone and environment variables
+     * @param {string} timezone
+     */
     async setTimezone(timezone) {
         await Settings.set("serverTimezone", timezone, "general");
         process.env.TZ = timezone;
         dayjs.tz.setDefault(timezone);
     }
 
+    /** Load the timeslots for maintenance */
     async generateMaintenanceTimeslots() {
 
         let list = await R.find("maintenance_timeslot", " generated_next = 0 AND start_date <= DATETIME('now') ");
@@ -237,6 +268,7 @@ class UptimeKumaServer {
 
     }
 
+    /** Stop the server */
     async stop() {
         clearTimeout(this.generateMaintenanceTimeslotsInterval);
     }

src/components/DockerHostDialog.vue

@@ -91,11 +91,16 @@ export default {
     },
     methods: {
 
+        /** Confirm deletion of docker host */
         deleteConfirm() {
             this.modal.hide();
             this.$refs.confirmDelete.show();
         },
 
+        /**
+         * Show specified docker host
+         * @param {number} dockerHostID
+         */
         show(dockerHostID) {
             if (dockerHostID) {
                 let found = false;
@@ -126,6 +131,7 @@ export default {
             this.modal.show();
         },
 
+        /** Add docker host */
         submit() {
             this.processing = true;
             this.$root.getSocket().emit("addDockerHost", this.dockerHost, this.id, (res) => {
@@ -144,6 +150,7 @@ export default {
             });
         },
 
+        /** Test the docker host */
         test() {
             this.processing = true;
             this.$root.getSocket().emit("testDockerHost", this.dockerHost, (res) => {
@@ -152,6 +159,7 @@ export default {
             });
         },
 
+        /** Delete this docker host */
         deleteDockerHost() {
             this.processing = true;
             this.$root.getSocket().emit("deleteDockerHost", this.id, (res) => {

src/components/notifications/Telegram.vue

@@ -42,6 +42,11 @@ export default {
         HiddenInput,
     },
     methods: {
+        /**
+         * Get the URL for telegram updates
+         * @param {string} [mode=masked] Should the token be masked?
+         * @returns {string} formatted URL
+         */
         telegramGetUpdatesURL(mode = "masked") {
             let token = `<${this.$t("YOUR BOT TOKEN HERE")}>`;
 
@@ -55,6 +60,8 @@ export default {
 
             return `https://api.telegram.org/bot${token}/getUpdates`;
         },
+
+        /** Get the telegram chat ID */
         async autoGetTelegramChatID() {
             try {
                 let res = await axios.get(this.telegramGetUpdatesURL("withToken"));

src/components/settings/Security.vue

@@ -191,6 +191,7 @@ export default {
             location.reload();
         },
 
+        /** Show confirmation dialog for disable auth */
         confirmDisableAuth() {
             this.$refs.confirmDisableAuth.show();
         },

src/mixins/datetime.js

@@ -12,6 +12,11 @@ export default {
     },
 
     methods: {
+        /**
+         * Convert value to UTC
+         * @param {string | number | Date | dayjs.Dayjs} value
+         * @returns {dayjs.Dayjs}
+         */
         toUTC(value) {
             return dayjs.tz(value, this.timezone).utc().format();
         },
@@ -34,6 +39,11 @@ export default {
             return this.datetimeFormat(value, "YYYY-MM-DD HH:mm:ss");
         },
 
+        /**
+         * Get time for maintenance
+         * @param {string | number | Date | dayjs.Dayjs} value
+         * @returns {string}
+         */
         datetimeMaintenance(value) {
             const inputDate = new Date(value);
             const now = new Date(Date.now());

src/mixins/socket.js

@@ -454,6 +454,10 @@ export default {
             socket.emit("getMonitorList", callback);
         },
 
+        /**
+         * Get list of maintenances
+         * @param {socketCB} callback
+         */
         getMaintenanceList(callback) {
             if (! callback) {
                 callback = () => { };
@@ -470,22 +474,49 @@ export default {
             socket.emit("add", monitor, callback);
         },
 
+        /**
+         * Adds a maintenace
+         * @param {Object} maintenance
+         * @param {socketCB} callback
+         */
         addMaintenance(maintenance, callback) {
             socket.emit("addMaintenance", maintenance, callback);
         },
 
+        /**
+         * Add monitors to maintenance
+         * @param {number} maintenanceID
+         * @param {number[]} monitors
+         * @param {socketCB} callback
+         */
         addMonitorMaintenance(maintenanceID, monitors, callback) {
             socket.emit("addMonitorMaintenance", maintenanceID, monitors, callback);
         },
 
+        /**
+         * Add status page to maintenance
+         * @param {number} maintenanceID
+         * @param {number} statusPages
+         * @param {socketCB} callback
+         */
         addMaintenanceStatusPage(maintenanceID, statusPages, callback) {
             socket.emit("addMaintenanceStatusPage", maintenanceID, statusPages, callback);
         },
 
+        /**
+         * Get monitors affected by maintenance
+         * @param {number} maintenanceID
+         * @param {socketCB} callback
+         */
         getMonitorMaintenance(maintenanceID, callback) {
             socket.emit("getMonitorMaintenance", maintenanceID, callback);
         },
 
+        /**
+         * Get status pages where maintenance is shown
+         * @param {number} maintenanceID
+         * @param {socketCB} callback
+         */
         getMaintenanceStatusPage(maintenanceID, callback) {
             socket.emit("getMaintenanceStatusPage", maintenanceID, callback);
         },
@@ -499,6 +530,11 @@ export default {
             socket.emit("deleteMonitor", monitorID, callback);
         },
 
+        /**
+         * Delete specified maintenance
+         * @param {number} maintenanceID
+         * @param {socketCB} callback
+         */
         deleteMaintenance(maintenanceID, callback) {
             socket.emit("deleteMaintenance", maintenanceID, callback);
         },

src/pages/EditMaintenance.vue

@@ -356,6 +356,7 @@ export default {
         });
     },
     methods: {
+        /** Initialise page */
         init() {
             this.affectedMonitors = [];
             this.selectedStatusPages = [];
@@ -414,6 +415,7 @@ export default {
             }
         },
 
+        /** Create new maintenance */
         async submit() {
             this.processing = true;
 
@@ -458,6 +460,11 @@ export default {
             }
         },
 
+        /**
+         * Add monitor to maintenance
+         * @param {number} maintenanceID
+         * @param {socketCB} callback
+         */
         async addMonitorMaintenance(maintenanceID, callback) {
             await this.$root.addMonitorMaintenance(maintenanceID, this.affectedMonitors, async (res) => {
                 if (!res.ok) {
@@ -470,6 +477,11 @@ export default {
             });
         },
 
+        /**
+         * Add status page to maintenance
+         * @param {number} maintenanceID
+         * @param {socketCB} callback
+         */
         async addMaintenanceStatusPage(maintenanceID, callback) {
             await this.$root.addMaintenanceStatusPage(maintenanceID, (this.showOnAllPages) ? this.selectedStatusPagesOptions : this.selectedStatusPages, async (res) => {
                 if (!res.ok) {

src/pages/MaintenanceDetails.vue

@@ -65,6 +65,7 @@ export default {
         this.init();
     },
     methods: {
+        /** Initialise page */
         init() {
             this.$root.getSocket().emit("getMonitorMaintenance", this.$route.params.id, (res) => {
                 if (res.ok) {
@@ -83,10 +84,12 @@ export default {
             });
         },
 
+        /** Confirm deletion */
         deleteDialog() {
             this.$refs.confirmDelete.show();
         },
 
+        /** Delete maintenance after showing confirmation */
         deleteMaintenance() {
             this.$root.deleteMaintenance(this.maintenance.id, (res) => {
                 if (res.ok) {

src/pages/ManageMaintenance.vue

@@ -133,15 +133,25 @@ export default {
             }
         },
 
+        /**
+         * Get maintenance URL
+         * @param {number} id
+         * @returns {string} Relative URL
+         */
         maintenanceURL(id) {
             return getMaintenanceRelativeURL(id);
         },
 
+        /**
+         * Show delete confirmation
+         * @param {number} maintenanceID
+         */
         deleteDialog(maintenanceID) {
             this.selectedMaintenanceID = maintenanceID;
             this.$refs.confirmDelete.show();
         },
 
+        /** Delete maintenance after showing confirmation dialog */
         deleteMaintenance() {
             this.$root.deleteMaintenance(this.selectedMaintenanceID, (res) => {
                 if (res.ok) {

src/util.js

@@ -315,6 +315,11 @@ function getMonitorRelativeURL(id) {
     return "/dashboard/" + id;
 }
 exports.getMonitorRelativeURL = getMonitorRelativeURL;
+/**
+ * Get relative path for maintenance
+ * @param id ID of maintenance
+ * @returns Formatted relative path
+ */
 function getMaintenanceRelativeURL(id) {
     return "/maintenance/" + id;
 }
@@ -361,6 +366,11 @@ function parseTimeFromTimeObject(obj) {
     return result;
 }
 exports.parseTimeFromTimeObject = parseTimeFromTimeObject;
+/**
+ * Convert ISO date to UTC
+ * @param input Date
+ * @returns ISO Date time
+ */
 function isoToUTCDateTime(input) {
     return dayjs(input).utc().format(exports.SQL_DATETIME_FORMAT);
 }
@@ -379,6 +389,12 @@ function utcToLocal(input, format = exports.SQL_DATETIME_FORMAT) {
     return dayjs.utc(input).local().format(format);
 }
 exports.utcToLocal = utcToLocal;
+/**
+ * Convert local datetime to UTC
+ * @param input Local date
+ * @param format Format to return
+ * @returns Date in requested format
+ */
 function localToUTC(input, format = exports.SQL_DATETIME_FORMAT) {
     return dayjs(input).utc().format(format);
 }

src/util.ts

@@ -352,6 +352,11 @@ export function getMonitorRelativeURL(id: string) {
     return "/dashboard/" + id;
 }
 
+/**
+ * Get relative path for maintenance
+ * @param id ID of maintenance
+ * @returns Formatted relative path
+ */
 export function getMaintenanceRelativeURL(id: string) {
     return "/maintenance/" + id;
 }
@@ -405,7 +410,11 @@ export function parseTimeFromTimeObject(obj : any) {
     return result;
 }
 
-
+/**
+ * Convert ISO date to UTC
+ * @param input Date
+ * @returns ISO Date time
+ */
 export function isoToUTCDateTime(input : string) {
     return dayjs(input).utc().format(SQL_DATETIME_FORMAT);
 }
@@ -424,6 +433,12 @@ export function utcToLocal(input : string, format = SQL_DATETIME_FORMAT) {
     return dayjs.utc(input).local().format(format);
 }
 
+/**
+ * Convert local datetime to UTC
+ * @param input Local date
+ * @param format Format to return
+ * @returns Date in requested format
+ */
 export function localToUTC(input : string, format = SQL_DATETIME_FORMAT) {
     return dayjs(input).utc().format(format);
 }