Add eslint jsdoc plugin and refine a bit the existing comments.

Signed-off-by: Jérôme Benoit <jerome.benoit@piment-noir.org>

diff --git a/.eslintrc b/.eslintrc
index 68996a2e275b396c17c543415c6d801885e9ffcd..570306d6fe7ac4add0025d38dbae07479d86349a 100644 (file)
--- a/.eslintrc
+++ b/.eslintrc
@@ -7,10 +7,12 @@
   "extends": [
     "eslint:recommended",
     "plugin:@typescript-eslint/recommended",
-    "plugin:@typescript-eslint/recommended-requiring-type-checking"
+    "plugin:@typescript-eslint/recommended-requiring-type-checking",
+    "plugin:jsdoc/recommended"
   ],
   "plugins": [
-    "@typescript-eslint"
+    "@typescript-eslint",
+    "jsdoc"
   ],
   "rules": {
     "indent": "off",

diff --git a/package-lock.json b/package-lock.json
index c350d280420a846b635480aad7d49240893b37fd..1368e9c80c2a304212efedc3adab99cd909e55eb 100644 (file)
--- a/package-lock.json
+++ b/package-lock.json
@@ -2580,6 +2580,12 @@
       "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==",
       "dev": true
     },
+    "comment-parser": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.1.2.tgz",
+      "integrity": "sha512-AOdq0i8ghZudnYv8RUnHrhTgafUGs61Rdz9jemU5x2lnZwAWyOq7vySo626K59e1fVKH1xSRorJwPVRLSWOoAQ==",
+      "dev": true
+    },
     "commist": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/commist/-/commist-1.1.0.tgz",
@@ -3930,6 +3936,78 @@
         }
       }
     },
+    "eslint-plugin-jsdoc": {
+      "version": "32.3.0",
+      "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-32.3.0.tgz",
+      "integrity": "sha512-zyx7kajDK+tqS1bHuY5sapkad8P8KT0vdd/lE55j47VPG2MeenSYuIY/M/Pvmzq5g0+3JB+P3BJGUXmHxtuKPQ==",
+      "dev": true,
+      "requires": {
+        "comment-parser": "1.1.2",
+        "debug": "^4.3.1",
+        "jsdoctypeparser": "^9.0.0",
+        "lodash": "^4.17.20",
+        "regextras": "^0.7.1",
+        "semver": "^7.3.4",
+        "spdx-expression-parse": "^3.0.1"
+      },
+      "dependencies": {
+        "debug": {
+          "version": "4.3.1",
+          "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.1.tgz",
+          "integrity": "sha512-doEwdvm4PCeK4K3RQN2ZC2BYUBaxwLARCqZmMjtF8a51J2Rb0xpVloFRnCODwqjpwnAoao4pelN8l3RJdv3gRQ==",
+          "dev": true,
+          "requires": {
+            "ms": "2.1.2"
+          }
+        },
+        "lodash": {
+          "version": "4.17.21",
+          "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
+          "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==",
+          "dev": true
+        },
+        "lru-cache": {
+          "version": "6.0.0",
+          "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-6.0.0.tgz",
+          "integrity": "sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==",
+          "dev": true,
+          "requires": {
+            "yallist": "^4.0.0"
+          }
+        },
+        "ms": {
+          "version": "2.1.2",
+          "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz",
+          "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==",
+          "dev": true
+        },
+        "semver": {
+          "version": "7.3.5",
+          "resolved": "https://registry.npmjs.org/semver/-/semver-7.3.5.tgz",
+          "integrity": "sha512-PoeGJYh8HK4BTO/a9Tf6ZG3veo/A7ZVsYrSA6J8ny9nb3B1VrpkuN+z9OE5wfE5p6H4LchYZsegiQgbJD94ZFQ==",
+          "dev": true,
+          "requires": {
+            "lru-cache": "^6.0.0"
+          }
+        },
+        "spdx-expression-parse": {
+          "version": "3.0.1",
+          "resolved": "https://registry.npmjs.org/spdx-expression-parse/-/spdx-expression-parse-3.0.1.tgz",
+          "integrity": "sha512-cbqHunsQWnJNE6KhVSMsMeH5H/L9EpymbzqTQ3uLwNCLZ1Q481oWaofqH7nO6V07xlXwY6PhQdQ2IedWx/ZK4Q==",
+          "dev": true,
+          "requires": {
+            "spdx-exceptions": "^2.1.0",
+            "spdx-license-ids": "^3.0.0"
+          }
+        },
+        "yallist": {
+          "version": "4.0.0",
+          "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz",
+          "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==",
+          "dev": true
+        }
+      }
+    },
     "eslint-scope": {
       "version": "5.1.1",
       "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-5.1.1.tgz",
@@ -5465,6 +5543,12 @@
       "integrity": "sha1-peZUwuWi3rXyAdls77yoDA7y9RM=",
       "dev": true
     },
+    "jsdoctypeparser": {
+      "version": "9.0.0",
+      "resolved": "https://registry.npmjs.org/jsdoctypeparser/-/jsdoctypeparser-9.0.0.tgz",
+      "integrity": "sha512-jrTA2jJIL6/DAEILBEh2/w9QxCuwmvNXIry39Ay/HVfhE3o2yVV0U44blYkqdHA/OKloJEqvJy0xU+GSdE2SIw==",
+      "dev": true
+    },
     "jsesc": {
       "version": "2.5.2",
       "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-2.5.2.tgz",
@@ -7791,6 +7875,12 @@
       "integrity": "sha512-ZOIzd8yVsQQA7j8GCSlPGXwg5PfmA1mrq0JP4nGhh54LaKN3xdai/vHUDu74pKwV8OxseMS65u2NImosQcSD0Q==",
       "dev": true
     },
+    "regextras": {
+      "version": "0.7.1",
+      "resolved": "https://registry.npmjs.org/regextras/-/regextras-0.7.1.tgz",
+      "integrity": "sha512-9YXf6xtW+qzQ+hcMQXx95MOvfqXFgsKDZodX3qZB0x2n5Z94ioetIITsBtvJbiOyxa/6s9AtyweBLCdPmPko/w==",
+      "dev": true
+    },
     "registry-auth-token": {
       "version": "3.4.0",
       "resolved": "https://registry.npmjs.org/registry-auth-token/-/registry-auth-token-3.4.0.tgz",

diff --git a/package.json b/package.json
index 5c7a5329be874555c4aa66f106e079e6380fc871..36b2313b5c33861f7ba891b8fce839a25ee3117c 100644 (file)
--- a/package.json
+++ b/package.json
@@ -69,6 +69,7 @@
     "clinic": "^8.0.1",
     "cross-env": "^7.0.3",
     "eslint": "^7.22.0",
+    "eslint-plugin-jsdoc": "^32.3.0",
     "mbt": "^1.1.1",
     "npm-check": "^5.9.2",
     "rollup": "^2.42.4",

diff --git a/src/charging-station/StationWorker.ts b/src/charging-station/StationWorker.ts
index bb2db88a4c749acafee441291b05dc8ef4fdf36e..20fb27ca04ae47a533f7109525f07a8e7bba1768 100644 (file)
--- a/src/charging-station/StationWorker.ts
+++ b/src/charging-station/StationWorker.ts
@@ -18,6 +18,9 @@ if (Utils.workerPoolInUse()) {
   }
 }
 
+/**
+ *
+ */
 function addMessageListener(): void {
   parentPort.on('message', (message) => {
     if (message.id === WorkerEvents.START_WORKER_ELEMENT) {
@@ -26,6 +29,9 @@ function addMessageListener(): void {
   });
 }
 
+/**
+ * @param data
+ */
 function startChargingStation(data: StationWorkerData): void {
   const station = new ChargingStation(data.index, data.templateFile);
   station.start();

diff --git a/src/charging-station/ocpp/OCPPRequestService.ts b/src/charging-station/ocpp/OCPPRequestService.ts
index a81974adf3ea527cbf34fdadd4ac28dfc8d054ad..2c2a8a5bed90647880397991a04b65353d7d06b8 100644 (file)
--- a/src/charging-station/ocpp/OCPPRequestService.ts
+++ b/src/charging-station/ocpp/OCPPRequestService.ts
@@ -68,7 +68,12 @@ export default abstract class OCPPRequestService {
         setTimeout(() => rejectCallback(new OCPPError(commandParams.code ? commandParams.code : ErrorType.GENERIC_ERROR, commandParams.message ? commandParams.message : `Timeout for message id '${messageId}' with content '${messageToSend}'`, commandParams.details ? commandParams.details : {})), Constants.OCPP_ERROR_TIMEOUT);
       }
 
-      // Function that will receive the request's response
+      /**
+       * Function that will receive the request's response
+       *
+       * @param payload
+       * @param requestPayload
+       */
       async function responseCallback(payload: Record<string, unknown> | string, requestPayload: Record<string, unknown>): Promise<void> {
         if (self.chargingStation.getEnableStatistics()) {
           self.chargingStation.statistics.addMessage(commandName, messageType);
@@ -78,7 +83,11 @@ export default abstract class OCPPRequestService {
         resolve(payload);
       }
 
-      // Function that will receive the request's rejection
+      /**
+       * Function that will receive the request's rejection
+       *
+       * @param error
+       */
       function rejectCallback(error: OCPPError): void {
         if (self.chargingStation.getEnableStatistics()) {
           self.chargingStation.statistics.addMessage(commandName, messageType);

diff --git a/src/utils/Utils.ts b/src/utils/Utils.ts
index e515d96875595011045400a398c18bfe30116ff7..1a0d7b70c1fb26feea3e95886b2ea0c4d4fb1126 100644 (file)
--- a/src/utils/Utils.ts
+++ b/src/utils/Utils.ts
@@ -184,7 +184,7 @@ export default class Utils {
 
   /**
    * @param  {number} [retryNumber=0]
-   * @return {number} - delay in milliseconds
+   * @returns {number} - delay in milliseconds
    */
   static exponentialDelay(retryNumber = 0): number {
     const delay = Math.pow(2, retryNumber) * 100;

diff --git a/src/worker/WorkerDynamicPool.ts b/src/worker/WorkerDynamicPool.ts
index 339aebcace72c63dce0472389664594b1100793b..eb570887f43d8df927b8310d9fb3166740f1f1c8 100644 (file)
--- a/src/worker/WorkerDynamicPool.ts
+++ b/src/worker/WorkerDynamicPool.ts
@@ -13,6 +13,8 @@ export default class WorkerDynamicPool<T> extends WorkerAbstract {
    * Create a new `WorkerDynamicPool`.
    *
    * @param {string} workerScript
+   * @param min
+   * @param max
    */
   constructor(workerScript: string, min: number, max: number,) {
     super(workerScript);
@@ -29,7 +31,7 @@ export default class WorkerDynamicPool<T> extends WorkerAbstract {
 
   /**
    *
-   * @return {Promise<void>}
+   * @returns {Promise<void>}
    * @public
    */
   // eslint-disable-next-line @typescript-eslint/no-empty-function
@@ -37,7 +39,7 @@ export default class WorkerDynamicPool<T> extends WorkerAbstract {
 
   /**
    *
-   * @return {Promise<void>}
+   * @returns {Promise<void>}
    * @public
    */
   // eslint-disable-next-line @typescript-eslint/require-await
@@ -47,7 +49,8 @@ export default class WorkerDynamicPool<T> extends WorkerAbstract {
 
   /**
    *
-   * @return {Promise<void>}
+   * @param elementData
+   * @returns {Promise<void>}
    * @public
    */
   public async addElement(elementData: T): Promise<void> {

diff --git a/src/worker/WorkerSet.ts b/src/worker/WorkerSet.ts
index 419243fe7536b48a6087767ab9d01df9321d1fc6..bda3018bf9a2df631dd9057dc6647844ebbf03f3 100644 (file)
--- a/src/worker/WorkerSet.ts
+++ b/src/worker/WorkerSet.ts
@@ -27,7 +27,8 @@ export default class WorkerSet<T> extends WorkerAbstract {
 
   /**
    *
-   * @return {Promise<void>}
+   * @param elementData
+   * @returns {Promise<void>}
    * @public
    */
   public async addElement(elementData: T): Promise<void> {
@@ -45,7 +46,7 @@ export default class WorkerSet<T> extends WorkerAbstract {
 
   /**
    *
-   * @return {Promise<void>}
+   * @returns {Promise<void>}
    * @public
    */
   public async start(): Promise<void> {
@@ -56,7 +57,7 @@ export default class WorkerSet<T> extends WorkerAbstract {
 
   /**
    *
-   * @return {Promise<void>}
+   * @returns {Promise<void>}
    * @public
    */
   public async stop(): Promise<void> {
@@ -68,7 +69,7 @@ export default class WorkerSet<T> extends WorkerAbstract {
 
   /**
    *
-   * @return {Promise}
+   * @returns {Promise}
    * @private
    */
   private startWorker(): void {

diff --git a/src/worker/WorkerStaticPool.ts b/src/worker/WorkerStaticPool.ts
index ab8e309f208f4655ff0ba6acb96929fea12c8d3d..97664dbae58ddb378aa03239610f6b68dcac056e 100644 (file)
--- a/src/worker/WorkerStaticPool.ts
+++ b/src/worker/WorkerStaticPool.ts
@@ -13,6 +13,7 @@ export default class WorkerStaticPool<T> extends WorkerAbstract {
    * Create a new `WorkerStaticPool`.
    *
    * @param {string} workerScript
+   * @param numberOfThreads
    */
   constructor(workerScript: string, numberOfThreads: number) {
     super(workerScript);
@@ -29,7 +30,7 @@ export default class WorkerStaticPool<T> extends WorkerAbstract {
 
   /**
    *
-   * @return {Promise<void>}
+   * @returns {Promise<void>}
    * @public
    */
   // eslint-disable-next-line @typescript-eslint/no-empty-function
@@ -37,7 +38,7 @@ export default class WorkerStaticPool<T> extends WorkerAbstract {
 
   /**
    *
-   * @return {Promise<void>}
+   * @returns {Promise<void>}
    * @public
    */
   public async stop(): Promise<void> {
@@ -46,7 +47,8 @@ export default class WorkerStaticPool<T> extends WorkerAbstract {
 
   /**
    *
-   * @return {Promise<void>}
+   * @param elementData
+   * @returns {Promise<void>}
    * @public
    */
   public async addElement(elementData: T): Promise<void> {