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

Added missing JSDoc comments
This commit is contained in:
Louis Lam 2023-01-15 13:10:17 +08:00 committed by GitHub
commit 49ac71e25c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
28 changed files with 273 additions and 13 deletions

View file

@ -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");

View file

@ -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) {

View file

@ -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) => {

View file

@ -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) => {

View file

@ -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) {

View file

@ -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);

View file

@ -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) {

View file

@ -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, {

View file

@ -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,

View file

@ -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);
}

View file

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

View file

@ -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;

View file

@ -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();
}

View file

@ -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`);

View file

@ -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) {

View file

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

View file

@ -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];

View file

@ -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);
}

View file

@ -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) => {

View file

@ -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"));

View file

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

View file

@ -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());

View file

@ -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);
},

View file

@ -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) {

View file

@ -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) {

View file

@ -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) {

View file

@ -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);
}

View file

@ -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);
}