From 2b42c3c828b4292fd64f0428c9a676c1bc4d6df7 Mon Sep 17 00:00:00 2001
From: Matthew Nickson <mnickson@sidingsmedia.com>
Date: Thu, 2 Jun 2022 00:32:05 +0100
Subject: [PATCH] Added JSDoc for src/components/*

Signed-off-by: Matthew Nickson <mnickson@sidingsmedia.com>
---
 src/components/CertificateInfo.vue    |  2 ++
 src/components/CertificateInfoRow.vue |  7 +++++
 src/components/Confirm.vue            |  7 +++++
 src/components/CopyableInput.vue      | 15 ++++++++++
 src/components/CountUp.vue            |  6 ++--
 src/components/Datetime.vue           |  2 ++
 src/components/HeartbeatBar.vue       |  9 ++++++
 src/components/HiddenInput.vue        |  8 ++++++
 src/components/Login.vue              |  1 +
 src/components/MonitorList.vue        |  8 ++++++
 src/components/NotificationDialog.vue |  9 ++++++
 src/components/PingChart.vue          |  1 +
 src/components/ProxyDialog.vue        |  7 +++++
 src/components/PublicGroupList.vue    | 12 ++++++++
 src/components/Status.vue             |  1 +
 src/components/Tag.vue                |  6 ++++
 src/components/TagsManager.vue        | 41 +++++++++++++++++++++++++++
 src/components/ToggleSection.vue      |  2 ++
 src/components/TwoFADialog.vue        |  8 ++++++
 src/components/Uptime.vue             |  3 ++
 20 files changed, 152 insertions(+), 3 deletions(-)

diff --git a/src/components/CertificateInfo.vue b/src/components/CertificateInfo.vue
index bb10f158d..cb1a82917 100644
--- a/src/components/CertificateInfo.vue
+++ b/src/components/CertificateInfo.vue
@@ -25,10 +25,12 @@ export default {
         CertificateInfoRow,
     },
     props: {
+        /** Object representing certificate */
         certInfo: {
             type: Object,
             required: true,
         },
+        /** Is the TLS certificate valid? */
         valid: {
             type: Boolean,
             required: true,
diff --git a/src/components/CertificateInfoRow.vue b/src/components/CertificateInfoRow.vue
index 3ac22f3b6..f02d1d7b9 100644
--- a/src/components/CertificateInfoRow.vue
+++ b/src/components/CertificateInfoRow.vue
@@ -56,12 +56,19 @@ export default {
         Datetime,
     },
     props: {
+        /** Object representing certificate */
         cert: {
             type: Object,
             required: true,
         },
     },
     methods: {
+        /**
+         * Format the subject of the certificate
+         * @param {Object} subject Object representing the certificates
+         * subject
+         * @returns {string}
+         */
         formatSubject(subject) {
             if (subject.O && subject.CN && subject.C) {
                 return `${subject.CN} - ${subject.O} (${subject.C})`;
diff --git a/src/components/Confirm.vue b/src/components/Confirm.vue
index 1bfe7fe4a..d369e0b5b 100644
--- a/src/components/Confirm.vue
+++ b/src/components/Confirm.vue
@@ -29,14 +29,17 @@ import { Modal } from "bootstrap";
 
 export default {
     props: {
+        /** Style of button */
         btnStyle: {
             type: String,
             default: "btn-primary",
         },
+        /** Text to use as yes */
         yesText: {
             type: String,
             default: "Yes",     // TODO: No idea what to translate this
         },
+        /** Text to use as no */
         noText: {
             type: String,
             default: "No",
@@ -50,9 +53,13 @@ export default {
         this.modal = new Modal(this.$refs.modal);
     },
     methods: {
+        /** Show the confirm dialog */
         show() {
             this.modal.show();
         },
+        /**
+         * @emits string A string that simply says "yes"
+         */
         yes() {
             this.$emit("yes");
         },
diff --git a/src/components/CopyableInput.vue b/src/components/CopyableInput.vue
index 1bccfa2ce..2e1dee766 100644
--- a/src/components/CopyableInput.vue
+++ b/src/components/CopyableInput.vue
@@ -25,33 +25,41 @@ let timeout;
 
 export default {
     props: {
+        /** ID of this input */
         id: {
             type: String,
             default: ""
         },
+        /** Type of input */
         type: {
             type: String,
             default: "text"
         },
+        /** The value of the input */
         modelValue: {
             type: String,
             default: ""
         },
+        /** A placeholder to use */
         placeholder: {
             type: String,
             default: ""
         },
+        /** Should the field auto complete */
         autocomplete: {
             type: String,
             default: undefined,
         },
+        /** Is the input required? */
         required: {
             type: Boolean
         },
+        /** Should the input be read only? */
         readonly: {
             type: String,
             default: undefined,
         },
+        /** Is the input disabled? */
         disabled: {
             type: String,
             default: undefined,
@@ -79,14 +87,21 @@ export default {
     },
     methods: {
 
+        /** Show the input */
         showInput() {
             this.visibility = "text";
         },
 
+        /** Hide the input */
         hideInput() {
             this.visibility = "password";
         },
 
+        /**
+         * Copy the provided text to the users clipboard
+         * @param {string} textToCopy
+         * @returns {Promise<void>}
+         */
         copyToClipboard(textToCopy) {
             this.icon = "check";
 
diff --git a/src/components/CountUp.vue b/src/components/CountUp.vue
index df1d1ac6c..9ce68507f 100644
--- a/src/components/CountUp.vue
+++ b/src/components/CountUp.vue
@@ -10,6 +10,7 @@ import { sleep } from "../util.ts";
 export default {
 
     props: {
+        /** Value to count */
         value: {
             type: [ String, Number ],
             default: 0,
@@ -18,6 +19,7 @@ export default {
             type: Number,
             default: 0.3,
         },
+        /** Unit of the value */
         unit: {
             type: String,
             default: "ms",
@@ -43,9 +45,7 @@ export default {
             let frames = 12;
             let step = Math.floor(diff / frames);
 
-            if (isNaN(step) || ! this.isNum || (diff > 0 && step < 1) || (diff < 0 && step > 1) || diff === 0) {
-                // Lazy to NOT this condition, hahaha.
-            } else {
+            if (! (isNaN(step) || ! this.isNum || (diff > 0 && step < 1) || (diff < 0 && step > 1) || diff === 0)) {
                 for (let i = 1; i < frames; i++) {
                     this.output += step;
                     await sleep(15);
diff --git a/src/components/Datetime.vue b/src/components/Datetime.vue
index fa68d02c7..3c66f5d6e 100644
--- a/src/components/Datetime.vue
+++ b/src/components/Datetime.vue
@@ -13,10 +13,12 @@ dayjs.extend(relativeTime);
 
 export default {
     props: {
+        /** Value of data time */
         value: {
             type: String,
             default: null,
         },
+        /** Should only the date be displayed? */
         dateOnly: {
             type: Boolean,
             default: false,
diff --git a/src/components/HeartbeatBar.vue b/src/components/HeartbeatBar.vue
index ce888a989..83923dd23 100644
--- a/src/components/HeartbeatBar.vue
+++ b/src/components/HeartbeatBar.vue
@@ -17,14 +17,17 @@
 
 export default {
     props: {
+        /** Size of the heart beat bar */
         size: {
             type: String,
             default: "big",
         },
+        /** ID of the monitor */
         monitorId: {
             type: Number,
             required: true,
         },
+        /** Array of the monitors heart beats */
         heartbeatList: {
             type: Array,
             default: null,
@@ -160,12 +163,18 @@ export default {
         this.resize();
     },
     methods: {
+        /** Resize the heartbeat bar */
         resize() {
             if (this.$refs.wrap) {
                 this.maxBeat = Math.floor(this.$refs.wrap.clientWidth / (this.beatWidth + this.beatMargin * 2));
             }
         },
 
+        /**
+         * Get the title of the beat
+         * @param {Object} beat Beat to get title from
+         * @returns {string}
+         */
         getBeatTitle(beat) {
             return `${this.$root.datetime(beat.time)}` + ((beat.msg) ? ` - ${beat.msg}` : "");
         },
diff --git a/src/components/HiddenInput.vue b/src/components/HiddenInput.vue
index d2327b9df..8fd68d4c4 100644
--- a/src/components/HiddenInput.vue
+++ b/src/components/HiddenInput.vue
@@ -24,25 +24,31 @@
 <script>
 export default {
     props: {
+        /** The value of the input */
         modelValue: {
             type: String,
             default: ""
         },
+        /** A placeholder to use */
         placeholder: {
             type: String,
             default: ""
         },
+        /** Maximum lenght of the input */
         maxlength: {
             type: Number,
             default: 255
         },
+        /** Should the field auto complete */
         autocomplete: {
             type: String,
             default: undefined,
         },
+        /** Is the input required? */
         required: {
             type: Boolean
         },
+        /** Should the input be read only? */
         readonly: {
             type: String,
             default: undefined,
@@ -68,9 +74,11 @@ export default {
 
     },
     methods: {
+        /** Show users input in plain text */
         showInput() {
             this.visibility = "text";
         },
+        /** Censor users input */
         hideInput() {
             this.visibility = "password";
         },
diff --git a/src/components/Login.vue b/src/components/Login.vue
index 987651e23..3a821881d 100644
--- a/src/components/Login.vue
+++ b/src/components/Login.vue
@@ -55,6 +55,7 @@ export default {
         };
     },
     methods: {
+        /** Submit the user details and attempt to log in */
         submit() {
             this.processing = true;
 
diff --git a/src/components/MonitorList.vue b/src/components/MonitorList.vue
index 7aeadd1e1..1d48af710 100644
--- a/src/components/MonitorList.vue
+++ b/src/components/MonitorList.vue
@@ -58,6 +58,7 @@ export default {
         Tag,
     },
     props: {
+        /** Should the scrollbar be shown */
         scrollbar: {
             type: Boolean,
         },
@@ -124,6 +125,7 @@ export default {
         window.removeEventListener("scroll", this.onScroll);
     },
     methods: {
+        /** Called when the user scrolls */
         onScroll() {
             if (window.top.scrollY <= 133) {
                 this.windowTop = window.top.scrollY;
@@ -131,9 +133,15 @@ export default {
                 this.windowTop = 133;
             }
         },
+        /**
+         * Get URL of monitor
+         * @param {number} id ID of monitor
+         * @returns {string} Relative URL of monitor
+         */
         monitorURL(id) {
             return getMonitorRelativeURL(id);
         },
+        /** Clear the search bar */
         clearSearchText() {
             this.searchText = "";
         }
diff --git a/src/components/NotificationDialog.vue b/src/components/NotificationDialog.vue
index 7a1f1a100..0ca95c222 100644
--- a/src/components/NotificationDialog.vue
+++ b/src/components/NotificationDialog.vue
@@ -125,11 +125,16 @@ export default {
     },
     methods: {
 
+        /** Show dialog to confirm deletion */
         deleteConfirm() {
             this.modal.hide();
             this.$refs.confirmDelete.show();
         },
 
+        /**
+         * Show settings for specified notification
+         * @param {number} notificationID ID of notification to show
+         */
         show(notificationID) {
             if (notificationID) {
                 this.id = notificationID;
@@ -152,6 +157,7 @@ export default {
             this.modal.show();
         },
 
+        /** Submit the form to the server */
         submit() {
             this.processing = true;
             this.$root.getSocket().emit("addNotification", this.notification, this.id, (res) => {
@@ -170,6 +176,7 @@ export default {
             });
         },
 
+        /** Test the notification endpoint */
         test() {
             this.processing = true;
             this.$root.getSocket().emit("testNotification", this.notification, (res) => {
@@ -178,6 +185,7 @@ export default {
             });
         },
 
+        /** Delete the notification endpoint */
         deleteNotification() {
             this.processing = true;
             this.$root.getSocket().emit("deleteNotification", this.id, (res) => {
@@ -190,6 +198,7 @@ export default {
             });
         },
         /**
+         * Get a unique default name for the notification
          * @param {keyof NotificationFormList} notificationKey
          * @return {string}
          */
diff --git a/src/components/PingChart.vue b/src/components/PingChart.vue
index 67bdc00c4..e472d898a 100644
--- a/src/components/PingChart.vue
+++ b/src/components/PingChart.vue
@@ -35,6 +35,7 @@ Chart.register(LineController, BarController, LineElement, PointElement, TimeSca
 export default {
     components: { LineChart },
     props: {
+        /** ID of monitor */
         monitorId: {
             type: Number,
             required: true,
diff --git a/src/components/ProxyDialog.vue b/src/components/ProxyDialog.vue
index 3070925c1..e52698f9f 100644
--- a/src/components/ProxyDialog.vue
+++ b/src/components/ProxyDialog.vue
@@ -130,11 +130,16 @@ export default {
     },
 
     methods: {
+        /** Show dialog to confirm delection */
         deleteConfirm() {
             this.modal.hide();
             this.$refs.confirmDelete.show();
         },
 
+        /**
+         * Show settings for specified proxy
+         * @param {number} proxyID ID of proxy to show
+         */
         show(proxyID) {
             if (proxyID) {
                 this.id = proxyID;
@@ -163,6 +168,7 @@ export default {
             this.modal.show();
         },
 
+        /** Submit form data for saving */
         submit() {
             this.processing = true;
             this.$root.getSocket().emit("addProxy", this.proxy, this.id, (res) => {
@@ -180,6 +186,7 @@ export default {
             });
         },
 
+        /** Delete this proxy */
         deleteProxy() {
             this.processing = true;
             this.$root.getSocket().emit("deleteProxy", this.id, (res) => {
diff --git a/src/components/PublicGroupList.vue b/src/components/PublicGroupList.vue
index df94eec98..137f734d1 100644
--- a/src/components/PublicGroupList.vue
+++ b/src/components/PublicGroupList.vue
@@ -72,10 +72,12 @@ export default {
         Tag,
     },
     props: {
+        /** Are we in edit mode? */
         editMode: {
             type: Boolean,
             required: true,
         },
+        /** Should tags be shown? */
         showTags: {
             type: Boolean,
         }
@@ -94,10 +96,20 @@ export default {
 
     },
     methods: {
+        /**
+         * Remove the specified group
+         * @param {number} index Index of group to remove
+         */
         removeGroup(index) {
             this.$root.publicGroupList.splice(index, 1);
         },
 
+        /**
+         * Remove a monitor from a group
+         * @param {number} groupIndex Index of group to remove monitor
+         * from
+         * @param {number} index Index of monitor to remove
+         */
         removeMonitor(groupIndex, index) {
             this.$root.publicGroupList[groupIndex].monitorList.splice(index, 1);
         },
diff --git a/src/components/Status.vue b/src/components/Status.vue
index 1985d8518..11897047a 100644
--- a/src/components/Status.vue
+++ b/src/components/Status.vue
@@ -5,6 +5,7 @@
 <script>
 export default {
     props: {
+        /** Current status of monitor */
         status: {
             type: Number,
             default: 0,
diff --git a/src/components/Tag.vue b/src/components/Tag.vue
index 3c9668502..0325d9900 100644
--- a/src/components/Tag.vue
+++ b/src/components/Tag.vue
@@ -20,14 +20,20 @@
 <script>
 export default {
     props: {
+        /** Object representing tag */
         item: {
             type: Object,
             required: true,
         },
+        /** Function to remove tag */
         remove: {
             type: Function,
             default: null,
         },
+        /**
+         * Size of tag
+         * @values normal, small
+         */
         size: {
             type: String,
             default: "normal",
diff --git a/src/components/TagsManager.vue b/src/components/TagsManager.vue
index 1a9212ca5..10f6a6f7d 100644
--- a/src/components/TagsManager.vue
+++ b/src/components/TagsManager.vue
@@ -139,6 +139,7 @@ export default {
         VueMultiselect,
     },
     props: {
+        /** Array of tags to be pre-selected */
         preSelectedTags: {
             type: Array,
             default: () => [],
@@ -241,9 +242,11 @@ export default {
         this.getExistingTags();
     },
     methods: {
+        /** Show the add tag dialog */
         showAddDialog() {
             this.modal.show();
         },
+        /** Get all existing tags */
         getExistingTags() {
             this.$root.getSocket().emit("getTags", (res) => {
                 if (res.ok) {
@@ -253,6 +256,10 @@ export default {
                 }
             });
         },
+        /**
+         * Delete the specified tag
+         * @param {Object} tag Object representing tag to delete
+         */
         deleteTag(item) {
             if (item.new) {
                 // Undo Adding a new Tag
@@ -262,6 +269,13 @@ export default {
                 this.deleteTags.push(item);
             }
         },
+        /**
+         * Set colour of text
+         * @param {Object} option Object representing color choice. If
+         * option.color is set, the text color will be white, else it
+         * be chosen based upon application theme
+         * @returns string
+         */
         textColor(option) {
             if (option.color) {
                 return "white";
@@ -269,6 +283,7 @@ export default {
                 return this.$root.theme === "light" ? "var(--bs-body-color)" : "inherit";
             }
         },
+        /** Add a draft tag */
         addDraftTag() {
             console.log("Adding Draft Tag: ", this.newDraftTag);
             if (this.newDraftTag.select != null) {
@@ -296,6 +311,7 @@ export default {
             }
             this.clearDraftTag();
         },
+        /** Remove a draft tag */
         clearDraftTag() {
             this.newDraftTag = {
                 name: null,
@@ -307,26 +323,51 @@ export default {
             };
             this.modal.hide();
         },
+        /**
+         * Add a tag asynchronously
+         * @param {Object} newTag Object representing new tag to add
+         * @returns {Promise<void>}
+         */
         addTagAsync(newTag) {
             return new Promise((resolve) => {
                 this.$root.getSocket().emit("addTag", newTag, resolve);
             });
         },
+        /**
+         * Add a tag to a monitor asynchronously
+         * @param {number} tagId ID of tag to add
+         * @param {number} monitorId ID of monitor to add tag to
+         * @param {string} value Value of tag
+         * @returns {Promise<void>}
+         */
         addMonitorTagAsync(tagId, monitorId, value) {
             return new Promise((resolve) => {
                 this.$root.getSocket().emit("addMonitorTag", tagId, monitorId, value, resolve);
             });
         },
+        /**
+         * Delete a tag from a monitor asynchronously
+         * @param {number} tagId ID of tag to remove
+         * @param {number} monitorId ID of monitor to remove tag from
+         * @param {string} value Value of tag
+         * @returns {Promise<void>}
+         */
         deleteMonitorTagAsync(tagId, monitorId, value) {
             return new Promise((resolve) => {
                 this.$root.getSocket().emit("deleteMonitorTag", tagId, monitorId, value, resolve);
             });
         },
+        /** Called as user types input */
         onEnter() {
             if (!this.validateDraftTag.invalid) {
                 this.addDraftTag();
             }
         },
+        /**
+         * Submit the form data
+         * @param {number} monitorId ID of monitor this change affects
+         * @returns {void}
+         */
         async submit(monitorId) {
             console.log(`Submitting tag changes for monitor ${monitorId}...`);
             this.processing = true;
diff --git a/src/components/ToggleSection.vue b/src/components/ToggleSection.vue
index daf9c00c2..5dfa3a637 100644
--- a/src/components/ToggleSection.vue
+++ b/src/components/ToggleSection.vue
@@ -29,10 +29,12 @@
 <script>
 export default {
     props: {
+        /** Heading to use */
         heading: {
             type: String,
             default: "",
         },
+        /** Should the selection be open by default? */
         defaultOpen: {
             type: Boolean,
             default: false,
diff --git a/src/components/TwoFADialog.vue b/src/components/TwoFADialog.vue
index 049f7c870..8dc9f9c79 100644
--- a/src/components/TwoFADialog.vue
+++ b/src/components/TwoFADialog.vue
@@ -100,18 +100,22 @@ export default {
         this.getStatus();
     },
     methods: {
+        /** Show the dialog */
         show() {
             this.modal.show();
         },
 
+        /** Show dialog to confirm enabling 2FA */
         confirmEnableTwoFA() {
             this.$refs.confirmEnableTwoFA.show();
         },
 
+        /** Show dialog to confirm disabling 2FA */
         confirmDisableTwoFA() {
             this.$refs.confirmDisableTwoFA.show();
         },
 
+        /** Prepare 2FA configuration */
         prepare2FA() {
             this.processing = true;
 
@@ -126,6 +130,7 @@ export default {
             });
         },
 
+        /** Save the current 2FA configuration */
         save2FA() {
             this.processing = true;
 
@@ -143,6 +148,7 @@ export default {
             });
         },
 
+        /** Disable 2FA for this user */
         disable2FA() {
             this.processing = true;
 
@@ -160,6 +166,7 @@ export default {
             });
         },
 
+        /** Verify the token generated by the user */
         verifyToken() {
             this.$root.getSocket().emit("verifyToken", this.token, this.currentPassword, (res) => {
                 if (res.ok) {
@@ -170,6 +177,7 @@ export default {
             });
         },
 
+        /** Get current status of 2FA */
         getStatus() {
             this.$root.getSocket().emit("twoFAStatus", (res) => {
                 if (res.ok) {
diff --git a/src/components/Uptime.vue b/src/components/Uptime.vue
index 487d62b72..8793b7a7b 100644
--- a/src/components/Uptime.vue
+++ b/src/components/Uptime.vue
@@ -5,14 +5,17 @@
 <script>
 export default {
     props: {
+        /** Monitor this represents */
         monitor: {
             type: Object,
             default: null,
         },
+        /** Type of monitor */
         type: {
             type: String,
             default: null,
         },
+        /** Is this a pill */
         pill: {
             type: Boolean,
             default: false,