Added JSDoc to ESLint (#3529)

* Added JSDoc to eslint rules

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

* Fixed JSDoc eslint errors

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

* Update the check-linters workflow to Node.js 20

---------

Signed-off-by: Matthew Nickson <mnickson@sidingsmedia.com>
Co-authored-by: Louis Lam <louislam@users.noreply.github.com>

extra/beta/update-version.js

@@ -36,6 +36,8 @@ if (! exists) {
 /**
  * Commit updated files
  * @param {string} version Version to update to
+ * @returns {void}
+ * @throws Error committing files
  */
 function commit(version) {
     let msg = "Update to " + version;
@@ -55,6 +57,7 @@ function commit(version) {
 /**
  * Create a tag with the specified version
  * @param {string} version Tag to create
+ * @returns {void}
  */
 function tag(version) {
     let res = childProcess.spawnSync("git", [ "tag", version ]);
@@ -68,6 +71,7 @@ function tag(version) {
  * Check if a tag exists for the specified version
  * @param {string} version Version to check
  * @returns {boolean} Does the tag already exist
+ * @throws Version is not valid
  */
 function tagExists(version) {
     if (! version) {

extra/download-dist.js

@@ -15,6 +15,7 @@ download(url);
 /**
  * Downloads the latest version of the dist from a GitHub release.
  * @param {string} url The URL to download from.
+ * @returns {void}
  *
  * Generated by Trelent
  */

extra/fs-rmSync.js

@@ -4,12 +4,12 @@ const fs = require("fs");
  * to avoid the runtime deprecation warning triggered for using `fs.rmdirSync` with `{ recursive: true }` in Node.js v16,
  * or the `recursive` property removing completely in the future Node.js version.
  * See the link below.
- *
  * @todo Once we drop the support for Node.js v14 (or at least versions before v14.14.0), we can safely replace this function with `fs.rmSync`, since `fs.rmSync` was add in Node.js v14.14.0 and currently we supports all the Node.js v14 versions that include the versions before the v14.14.0, and this function have almost the same signature with `fs.rmSync`.
  * @link https://nodejs.org/docs/latest-v16.x/api/deprecations.html#dep0147-fsrmdirpath--recursive-true- the deprecation infomation of `fs.rmdirSync`
  * @link https://nodejs.org/docs/latest-v16.x/api/fs.html#fsrmsyncpath-options the document of `fs.rmSync`
  * @param {fs.PathLike} path Valid types for path values in "fs".
- * @param {fs.RmDirOptions} [options] options for `fs.rmdirSync`, if `fs.rmSync` is available and property `recursive` is true, it will automatically have property `force` with value `true`.
+ * @param {fs.RmDirOptions} options options for `fs.rmdirSync`, if `fs.rmSync` is available and property `recursive` is true, it will automatically have property `force` with value `true`.
+ * @returns {void}
  */
 const rmSync = (path, options) => {
     if (typeof fs.rmSync === "function") {

extra/simple-dns-server.js

@@ -138,7 +138,7 @@ server.listen({
 /**
  * Get human readable request type from request code
  * @param {number} code Request code to translate
- * @returns {string} Human readable request type
+ * @returns {string|void} Human readable request type
  */
 function type(code) {
     for (let name in Packet.TYPE) {

extra/simple-mqtt-server.js

@@ -7,11 +7,17 @@ class SimpleMqttServer {
     aedes = require("aedes")();
     server = require("net").createServer(this.aedes.handle);
 
+    /**
+     * @param {number} port Port to listen on
+     */
     constructor(port) {
         this.port = port;
     }
 
-    /** Start the MQTT server */
+    /**
+     * Start the MQTT server
+     * @returns {void}
+     */
     start() {
         this.server.listen(this.port, () => {
             console.log("server started and listening on port ", this.port);

extra/update-language-files/index.js

@@ -12,6 +12,7 @@ import rmSync from "../fs-rmSync.js";
  * created with this code if one does not already exist
  * @param {string} baseLang The second base language file to copy. This
  * will be ignored if set to "en" as en.js is copied by default
+ * @returns {void}
  */
 function copyFiles(langCode, baseLang) {
     if (fs.existsSync("./languages")) {
@@ -33,7 +34,8 @@ function copyFiles(langCode, baseLang) {
 /**
  * Update the specified language file
  * @param {string} langCode Language code to update
- * @param {string} baseLang Second language to copy keys from
+ * @param {string} baseLangCode Second language to copy keys from
+ * @returns {void}
  */
 async function updateLanguage(langCode, baseLangCode) {
     const en = (await import("./languages/en.js")).default;

extra/update-version.js

@@ -39,6 +39,8 @@ if (! exists) {
 /**
  * Commit updated files
  * @param {string} version Version to update to
+ * @returns {void}
+ * @throws Error when committing files
  */
 function commit(version) {
     let msg = "Update to " + version;
@@ -55,6 +57,7 @@ function commit(version) {
 /**
  * Create a tag with the specified version
  * @param {string} version Tag to create
+ * @returns {void}
  */
 function tag(version) {
     let res = childProcess.spawnSync("git", [ "tag", version ]);
@@ -65,6 +68,7 @@ function tag(version) {
  * Check if a tag exists for the specified version
  * @param {string} version Version to check
  * @returns {boolean} Does the tag already exist
+ * @throws Version is not valid
  */
 function tagExists(version) {
     if (! version) {

extra/update-wiki-version.js

@@ -13,6 +13,7 @@ updateWiki(newVersion);
 /**
  * Update the wiki with new version number
  * @param {string} newVersion Version to update to
+ * @returns {void}
  */
 function updateWiki(newVersion) {
     const wikiDir = "./tmp/wiki";
@@ -46,6 +47,7 @@ function updateWiki(newVersion) {
 /**
  * Check if a directory exists and then delete it
  * @param {string} dir Directory to delete
+ * @returns {void}
  */
 function safeDelete(dir) {
     if (fs.existsSync(dir)) {