Update eslint configuration and adding comment to all functions which…

… do not have them. (project-chip#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
SiliconLabs · Sep 5, 2024 · 6f8c18a · 6f8c18a
1 parent e26dcfe
commit 6f8c18a
Show file tree

Hide file tree

Showing 131 changed files with 28,230 additions and 14,619 deletions.
diff --git a/.eslintignore b/.eslintignore
@@ -1,2 +1,5 @@
 /dist
 src-script/download-artifact.js
+/spa
+/generated-html
+/src-electron/generator/matter
diff --git a/.eslintrc.js b/.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
+      }
+    }
+  ]
 }
diff --git a/.husky/pre-commit b/.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

diff --git a/README.md b/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)

diff --git a/docs/api.md b/docs/api.md
diff --git a/docs/helpers.md b/docs/helpers.md
diff --git a/package.json b/package.json
@@ -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": {

diff --git a/src-electron/client/ipc-client.js b/src-electron/client/ipc-client.js
@@ -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}`)
 }

diff --git a/src-electron/db/db-api.js b/src-electron/db/db-api.js
@@ -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.')

diff --git a/src-electron/db/query-access.js b/src-electron/db/query-access.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(

diff --git a/src-electron/db/query-atomic.js b/src-electron/db/query-atomic.js
@@ -20,6 +20,7 @@
  *
  * @module DB API: zcl database access
  */
+
 const dbApi = require('./db-api.js')
 const dbCache = require('./db-cache.js')
 const dbMapping = require('./db-mapping.js')
@@ -42,7 +43,12 @@ FROM ATOMIC
 const cacheKey = 'atomic'
 
 // Raw query versions without caching.
-
+/**
+ * Get all atomic data type information
+ * @param {*} db
+ * @param {*} packageId
+ * @returns atomic data types
+ */
 async function selectAllAtomics(db, packageId) {
   let rows = await dbApi.dbAll(
     db,

diff --git a/src-electron/db/query-attribute.js b/src-electron/db/query-attribute.js
@@ -20,6 +20,7 @@
  *
  * @module DB API: attribute queries.
  */
+
 const dbApi = require('./db-api.js')
 const dbMapping = require('./db-mapping.js')
 const dbCache = require('./db-cache')
@@ -565,7 +566,6 @@ async function selectAttributeDetailsFromEnabledClusters(
  * Union is used to get separate entries of attributes w.r.t to default, minimum
  * and maximum values
  */
-
 async function selectAttributeBoundDetails(
   db,
   endpointsAndClusters,
@@ -793,6 +793,15 @@ async function selectReportableAttributeDetailsFromEnabledClustersAndEndpoints(
     .then((rows) => rows.map(mapFunction))
 }
 
+/**
+ * Get attribute data by attribute code.
+ * @param {*} db
+ * @param {*} packageIds
+ * @param {*} clusterCode
+ * @param {*} attributeCode
+ * @param {*} manufacturerCode
+ * @returns promise of attribute data
+ */
 async function selectAttributeByCode(
   db,
   packageIds,
@@ -818,6 +827,15 @@ async function selectAttributeByCode(
   }
 }
 
+/**
+ * Get attribute information by code for attributes which are not global.
+ * @param {*} db
+ * @param {*} packageIds
+ * @param {*} clusterCode
+ * @param {*} attributeCode
+ * @param {*} manufacturerCode
+ * @returns promise of attribute data
+ */
 async function selectNonGlobalAttributeByCode(
   db,
   packageIds,
@@ -878,6 +896,14 @@ WHERE A.PACKAGE_REF IN (${dbApi.toInClause(packageIds)})
     .then(dbMapping.map.attribute)
 }
 
+/**
+ * Get global attributes by their attribute code.
+ * @param {*} db
+ * @param {*} packageIds
+ * @param {*} attributeCode
+ * @param {*} manufacturerCode
+ * @returns promise of global attribute data
+ */
 async function selectGlobalAttributeByCode(
   db,
   packageIds,

diff --git a/src-electron/db/query-bitmap.js b/src-electron/db/query-bitmap.js
@@ -20,6 +20,7 @@
  *
  * @module DB API: zcl database access
  */
+
 const dbApi = require('./db-api')
 const dbCache = require('./db-cache')
 const dbMapping = require('./db-mapping')
@@ -51,6 +52,13 @@ WHERE PACKAGE_REF = ? ORDER BY NAME`,
   return rows.map(dbMapping.map.bitmap)
 }
 
+/**
+ * Get bitmap by name from the given package IDs.
+ * @param {*} db
+ * @param {*} packageIds
+ * @param {*} name
+ * @returns promise of bitmap
+ */
 async function selectBitmapByName(db, packageIds, name) {
   return dbApi
     .dbGet(
@@ -104,6 +112,12 @@ async function selectBitmapByNameAndClusterId(db, name, clusterId, packageIds) {
   }
 }
 
+/**
+ * Get Bitmap information by Bitmap ID.
+ * @param {*} db
+ * @param {*} id
+ * @returns Promise of bitmap
+ */
 async function selectBitmapById(db, id) {
   return dbApi
     .dbGet(

diff --git a/src-electron/db/query-cluster.js b/src-electron/db/query-cluster.js
@@ -20,6 +20,7 @@
  *
  * @module DB API: cluster queries.
  */
+
 const dbApi = require('./db-api.js')
 const dbMapping = require('./db-mapping.js')