Update eslint configuration and adding comment to all functions which do not have them. (#1414)

- Update eslint to throw errors when functions don't have documentation.
- Ignoring eslint missing comments for spa, generated-html and src-electron/generator/matter
- Update comments on all the js functions
- Add eslint to pre-commit hook
- Adding api documentation update to pre-commit hook
- Using npx jsdoc2md src-shared/**/*.js src-electron/**/*.js > docs/api.md for api.md update on each commit
- Updating API documentation
- Updating the modules for all files in src-shared and src-electron such that their documentation is generated properly using jsdoc2md
- Adding 2 scripts to generate api documentation  and helper documentation such that users can now have one place to know about every helper available.
- The 2 scripts are called as part of the pre-commit hook and fails if documentation is not added for any function.
- The documentation for api.md and helpers.md is updated as part of the commit using the pre-commit hook
- Clean up all the associated files and functions such that jsdoc2md works efficiently
- Ignoring src directory for eslint
- Updating the README.md with the template helper documentation link
- Adding vue files to the ignore list in eslint
- JIRA: ZAPP-1143

- Adding comments for the one missing file

Author: brdandu

.eslintignore

@@ -1,2 +1,5 @@
 /dist
 src-script/download-artifact.js
+/spa
+/generated-html
+/src-electron/generator/matter

.eslintrc.js

@@ -62,6 +62,26 @@ module.exports = {
 
     // random rules added
     'no-undef': 'off',
-    'no-unused-vars': 'off'
-  }
+    'no-unused-vars': 'off',
+    'require-jsdoc': [
+      'error',
+      {
+        require: {
+          FunctionDeclaration: true,
+          MethodDefinition: true,
+          ClassDeclaration: false,
+          ArrowFunctionExpression: false,
+          FunctionExpression: false
+        }
+      }
+    ]
+  },
+  overrides: [
+    {
+      files: ['test/**/*.js', 'src/**/*.vue'], // Path to the directory you want to ignore
+      rules: {
+        'require-jsdoc': 'off' // Disable the require-jsdoc rule for this directory
+      }
+    }
+  ]
 }

.husky/pre-commit

@@ -5,10 +5,13 @@ echo "🚀   > Pretty quick reformat..."
 npx pretty-quick --staged
 
 echo "🚀   > JSdoc regen..."
-npx jsdoc src-electron src-shared -r -d ./generated-html/
+node src-script/generate-all-api-docs.js
+node src-script/generate-template-helper-docs.js
+git add docs/api.md
+git add docs/helpers.md
 
 echo "🚀   > Eslint..."
-npx eslint --ext .js,.vue src src-electron src-shared src-script test
+npx eslint .
 
 echo "🚀   > Reset version in package.json to 0.0.0..."
 src-script/zap-update-package-version.js -fake

README.md

@@ -37,6 +37,7 @@ This software is licensed under [Apache 2.0 license](LICENSE.txt).
 
 ## Detailed Developer Documentation
 
+- [ZAP Template Helpers](docs/helpers.md)
 - [FAQ/Developer dependencies](docs/faq.md)
 - [Release instructions](docs/release.md)
 - [Development Instructions](docs/development-instructions.md)

docs/api.md

@@ -51,7 +51,8 @@
     "build-spa": "node src-script/build-spa.js",
     "build-backend": "node src-script/build-backend.js",
     "doc": "jsdoc src-electron src-shared -r -u docs -d ./generated-html/ README.md",
-    "apidoc": "jsdoc2md src-shared/**/*.js src-electron/**/*.js > docs/api.md",
+    "api-doc": "node src-script/generate-all-api-docs.js",
+    "helper-doc": "node src-script/generate-template-helper-docs.js",
     "format-code": "pretty-quick",
     "pretty-quick": "pretty-quick",
     "version-stamp": "node src-script/zap-versionstamp.js",
@@ -213,7 +214,7 @@
   ],
   "husky": {
     "hooks": {
-      "pre-commit": "pretty-quick --staged && jsdoc src-electron src-shared -r -d ./generated-html/ && eslint --ext .js,.vue src src-electron src-shared src-script test"
+      "pre-commit": "pretty-quick --staged && jsdoc src-electron src-shared -r -d ./generated-html/ && eslint ."
     }
   },
   "build": {

docs/helpers.md

@@ -15,6 +15,12 @@
  *    limitations under the License.
  */
 
+/**
+ * This module provides IPC Client functionality.
+ *
+ * @module IPC Client API: Inter-process communication
+ */
+
 const env = require('../util/env')
 const ipcServer = require('../server/ipc-server')
 const util = require('../util/util.js')
@@ -28,6 +34,10 @@ const client = {
 
 let lastPong = ''
 
+/**
+ * Log ipc client message
+ * @param {*} msg
+ */
 function log(msg) {
   env.logIpc(`Ipc client: ${msg}`)
 }

package.json

@@ -38,6 +38,12 @@ const dbMapping = require('./db-mapping.js')
 //
 let inTransaction = false
 
+/**
+ * Begin Database transaction.
+ * @param {*} db
+ * @param {*} resolve
+ * @param {*} reject
+ */
 function executeBeginTransaction(db, resolve, reject) {
   db.run('BEGIN TRANSACTION', [], function (err) {
     if (err) {
@@ -50,6 +56,12 @@ function executeBeginTransaction(db, resolve, reject) {
   })
 }
 
+/**
+ * Delay database transaction.
+ * @param {*} db
+ * @param {*} resolve
+ * @param {*} reject
+ */
 function delayBeginTransaction(db, resolve, reject) {
   let cnt = 0
   let interval = setInterval(() => {
@@ -485,6 +497,13 @@ async function determineIfSchemaShouldLoad(db, filePath, crc) {
   return result
 }
 
+/**
+ * Update the CRC of the sql schema file.
+ * @param {*} db
+ * @param {*} filePath
+ * @param {*} crc
+ * @returns promise of insert transaction.
+ */
 async function updateCurrentSchemaCrc(db, filePath, crc) {
   return dbInsert(
     db,
@@ -493,6 +512,12 @@ async function updateCurrentSchemaCrc(db, filePath, crc) {
   )
 }
 
+/**
+ * Load SQL Schema
+ * @param {*} db
+ * @param {*} schemaContent
+ * @returns Promise of loaded schema
+ */
 async function performSchemaLoad(db, schemaContent) {
   return new Promise((resolve, reject) => {
     env.logSql('Loading schema.')

src-electron/client/ipc-client.js

@@ -23,6 +23,12 @@
 const dbApi = require('./db-api.js')
 const dbMapping = require('./db-mapping.js')
 
+/**
+ * Get access operations for package IDs given.
+ * @param {*} db
+ * @param {*} packageIds
+ * @returns promise of access operation.
+ */
 async function selectAccessOperations(db, packageIds) {
   return dbApi
     .dbAll(
@@ -36,6 +42,12 @@ SELECT NAME, DESCRIPTION FROM OPERATION WHERE PACKAGE_REF IN (${dbApi.toInClause
     .then((rows) => rows.map(dbMapping.map.accessOperation))
 }
 
+/**
+ * Get access roles for package IDs given.
+ * @param {*} db
+ * @param {*} packageIds
+ * @returns promise of access roles.
+ */
 async function selectAccessRoles(db, packageIds) {
   return dbApi
     .dbAll(
@@ -49,6 +61,12 @@ SELECT NAME, DESCRIPTION, LEVEL FROM ROLE WHERE PACKAGE_REF IN (${dbApi.toInClau
     .then((rows) => rows.map(dbMapping.map.accessRole))
 }
 
+/**
+ * Get access modifiers for package IDs given.
+ * @param {*} db
+ * @param {*} packageIds
+ * @returns promise of access modifiers.
+ */
 async function selectAccessModifiers(db, packageIds) {
   return dbApi
     .dbAll(
@@ -99,6 +117,12 @@ ORDER BY OPERATION.NAME, ROLE.NAME, ACCESS_MODIFIER.NAME
     .then((rows) => rows.map(dbMapping.map.access))
 }
 
+/**
+ * Get attribute access information for the attribute id given.
+ * @param {*} db
+ * @param {*} attributeId
+ * @returns Promise of attribute access information
+ */
 async function selectAttributeAccess(db, attributeId) {
   return dbApi
     .dbAll(
@@ -128,6 +152,12 @@ ORDER BY OPERATION.NAME, ROLE.NAME, ACCESS_MODIFIER.NAME
     .then((rows) => rows.map(dbMapping.map.access))
 }
 
+/**
+ * Get command access information for the attribute id given.
+ * @param {*} db
+ * @param {*} commandId
+ * @returns Promise of command access information
+ */
 async function selectCommandAccess(db, commandId) {
   return dbApi
     .dbAll(
@@ -157,6 +187,12 @@ ORDER BY OPERATION.NAME, ROLE.NAME, ACCESS_MODIFIER.NAME
     .then((rows) => rows.map(dbMapping.map.access))
 }
 
+/**
+ * Get event access information for the attribute id given.
+ * @param {*} db
+ * @param {*} eventId
+ * @returns Promise of event access information
+ */
 async function selectEventAccess(db, eventId) {
   return dbApi
     .dbAll(