- Updating the modules for all files in src-shared and src-electron s…

…uch 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
- JIRA: ZAPP-1143

.husky/pre-commit

@@ -5,9 +5,10 @@ echo "🚀   > Pretty quick reformat..."
 npx pretty-quick --staged
 
 echo "🚀   > JSdoc regen..."
-npx jsdoc src-electron src-shared -r -d ./generated-html/
-npx jsdoc2md src-shared/**/*.js src-electron/**/*.js > docs/api.md
+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 .

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",

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')

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')

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')

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')

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')
 

src-electron/db/query-command.js

@@ -20,6 +20,7 @@
  *
  * @module DB API: command queries.
  */
+
 const dbApi = require('./db-api.js')
 const dbMapping = require('./db-mapping.js')
 

src-electron/db/query-config.js

@@ -20,6 +20,7 @@
  *
  * @module DB API: user configuration queries against the database.
  */
+
 const dbApi = require('./db-api.js')
 const dbMapping = require('./db-mapping.js')
 const queryPackage = require('./query-package.js')

src-electron/db/query-data-type-discriminator.js

@@ -16,7 +16,9 @@
  */
 
 /**
- * This module provides queries for discriminators
+ * This module provides queries for data type discriminator
+ *
+ * @module DB API: Data type discriminator queries against the database.
  */
 
 const dbApi = require('./db-api')

src-electron/db/query-data-type.js

@@ -17,6 +17,8 @@
 
 /**
  * This module provides queries for data types
+ *
+ * @module DB API: Data type queries against the database.
  */
 
 const dbApi = require('./db-api')

src-electron/db/query-device-type.js

@@ -20,6 +20,7 @@
  *
  * @module DB API: device type database access
  */
+
 const dbApi = require('./db-api')
 const dbMapping = require('./db-mapping')
 

src-electron/db/query-endpoint-type.js

@@ -20,6 +20,7 @@
  *
  * @module DB API: endpoint type queries against the database.
  */
+
 const dbApi = require('./db-api.js')
 const dbMapping = require('./db-mapping.js')
 

src-electron/db/query-endpoint.js

@@ -20,6 +20,7 @@
  *
  * @module DB API: endpoint configuration queries against the database.
  */
+
 const dbApi = require('./db-api.js')
 const bin = require('../util/bin')
 const dbMapping = require('./db-mapping.js')

src-electron/db/query-enum.js

@@ -18,8 +18,9 @@
 /**
  * This module provides queries for enums.
  *
- * @module DB API: zcl database access
+ * @module DB API: zcl database enum access
  */
+
 const dbApi = require('./db-api')
 const dbCache = require('./db-cache')
 const dbMapping = require('./db-mapping')

src-electron/db/query-event.js

@@ -20,6 +20,7 @@
  *
  * @module DB API: event queries.
  */
+
 const dbApi = require('./db-api.js')
 const dbMapping = require('./db-mapping.js')
 

src-electron/db/query-impexp.js

@@ -20,6 +20,7 @@
  *
  * @module DB API: package-based queries.
  */
+
 const dbApi = require('./db-api')
 const dbEnums = require('../../src-shared/db-enum')
 const dbMapping = require('./db-mapping.js')

src-electron/db/query-loader.js

@@ -20,6 +20,7 @@
  *
  * @module DB API: zcl loading queries
  */
+
 const env = require('../util/env')
 const dbApi = require('./db-api.js')
 const queryNotification = require('../db/query-package-notification')

src-electron/db/query-number.js

@@ -16,8 +16,11 @@
  */
 
 /**
- * This module provides queries for numbers
+ * This module provides queries for numbers.
+ *
+ * @module DB API: zcl database number access
  */
+
 const dbApi = require('./db-api')
 const dbMapping = require('./db-mapping')
 const dbCache = require('./db-cache')

src-electron/db/query-package.js

@@ -20,6 +20,7 @@
  *
  * @module DB API: package-based queries.
  */
+
 const dbApi = require('./db-api.js')
 const dbMapping = require('./db-mapping.js')
 const dbEnum = require('../../src-shared/db-enum.js')

src-electron/db/query-session-zcl.js

@@ -22,6 +22,7 @@
  *
  * @module DB API: zcl database access
  */
+
 const dbApi = require('./db-api.js')
 const dbMapping = require('./db-mapping.js')
 const dbEnum = require('../../src-shared/db-enum.js')

src-electron/db/query-session.js

@@ -20,6 +20,7 @@
  *
  * @module DB API: session related queries.
  */
+
 const dbApi = require('./db-api.js')
 const dbMapping = require('./db-mapping.js')
 const util = require('../util/util.js')

src-electron/db/query-string.js

@@ -16,7 +16,9 @@
  */
 
 /**
- * This module provides queries for strings
+ * This module provides queries for strings.
+ *
+ * @module DB API: zcl database strings access
  */
 
 const dbApi = require('./db-api')

src-electron/db/query-struct.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')

src-electron/db/query-util.js

@@ -21,6 +21,7 @@
  *
  * @module DB API: zcl database access
  */
+
 const dbApi = require('./db-api')
 
 /**

src-electron/db/query-zcl.js

@@ -20,6 +20,7 @@
  *
  * @module DB API: zcl database access
  */
+
 const dbApi = require('./db-api')
 const dbMapping = require('./db-mapping')
 const queryAtomic = require('./query-atomic')

src-electron/generator/generation-engine.js

@@ -18,6 +18,7 @@
 /**
  * @module JS API: generator logic
  */
+
 const _ = require('lodash')
 const fs = require('fs')
 const fsPromise = fs.promises

src-electron/generator/helper-access.js

@@ -15,14 +15,22 @@
  *    limitations under the License.
  */
 
+/**
+ * This module contains the API for templating. For more detailed instructions, read {@tutorial template-tutorial}
+ *
+ * @module Templating API: Access helpers
+ */
+
 const queryAccess = require('../db/query-access')
 const templateUtil = require('./template-util')
 const dbEnum = require('../../src-shared/db-enum')
 
 /**
- * This module contains the API for templating. For more detailed instructions, read {@tutorial template-tutorial}
+ * Collects the default access list
  *
- * @module Templating API: Access helpers
+ * @param {*} ctx
+ * @param {*} entityType
+ * @returns Promise of default access
  */
 async function collectDefaultAccessList(ctx, entityType) {
   let packageIds = await templateUtil.ensureZclPackageIds(ctx)

src-electron/generator/helper-attribute.js

@@ -15,6 +15,12 @@
  *    limitations under the License.
  */
 
+/**
+ * This module contains the API for templating. For more detailed instructions, read {@tutorial template-tutorial}
+ *
+ * @module Templating API: Attribute helpers
+ */
+
 const queryAttribute = require('../db/query-attribute')
 const templateUtil = require('./template-util')
 

src-electron/generator/helper-c.js

@@ -15,6 +15,12 @@
  *    limitations under the License.
  */
 
+/**
+ * This module contains the API for templating. For more detailed instructions, read {@tutorial template-tutorial}
+ *
+ * @module Templating API: C formatting helpers
+ */
+
 const queryZcl = require('../db/query-zcl.js')
 const queryPackage = require('../db/query-package.js')
 const templateUtil = require('./template-util.js')
@@ -25,12 +31,6 @@ const _ = require('lodash')
 const dbEnum = require('../../src-shared/db-enum.js')
 const envConfig = require('../util/env')
 
-/**
- * This module contains the API for templating. For more detailed instructions, read {@tutorial template-tutorial}
- *
- * @module Templating API: C formatting helpers
- */
-
 /**
  * Given a hex number, it prints the offset, which is the index of the first non-zero bit.
  * @param {*} hex

src-electron/generator/helper-command.js

@@ -15,6 +15,12 @@
  *    limitations under the License.
  */
 
+/**
+ * This module contains the API for templating. For more detailed instructions, read {@tutorial template-tutorial}
+ *
+ * @module Templating API: Command helpers
+ */
+
 const queryCommand = require('../db/query-command.js')
 const templateUtil = require('./template-util.js')
 const types = require('../util/types.js')

src-electron/generator/helper-endpointconfig.js

@@ -15,6 +15,12 @@
  *    limitations under the License.
  */
 
+/**
+ * This module contains the API for templating. For more detailed instructions, read {@tutorial template-tutorial}
+ *
+ * @module Templating API: Matter endpoint config helpers
+ */
+
 const cHelper = require('./helper-c.js')
 const templateUtil = require('./template-util')
 const queryEndpoint = require('../db/query-endpoint.js')

src-electron/generator/helper-future.js

@@ -14,6 +14,13 @@
  *    See the License for the specific language governing permissions and
  *    limitations under the License.
  */
+
+/**
+ * This module contains the API for templating. For more detailed instructions, read {@tutorial template-tutorial}
+ *
+ * @module Templating API: Future helpers
+ */
+
 const futureKey = 'futures'
 const valueKey = 'futureValues'
 const timeoutMessage = '!---timeout---!'

src-electron/generator/helper-sdkextension.js

@@ -15,6 +15,12 @@
  *    limitations under the License.
  */
 
+/**
+ * This module contains the API for templating. For more detailed instructions, read {@tutorial template-tutorial}
+ *
+ * @module Templating API: SDK extension helpers
+ */
+
 const dbEnum = require('../../src-shared/db-enum.js')
 const templateUtil = require('./template-util.js')
 const util = require('../util/util.js')

src-electron/generator/helper-session.js

@@ -20,6 +20,7 @@
  *
  * @module Templating API: user-data specific helpers
  */
+
 const templateUtil = require('./template-util.js')
 const queryImpexp = require('../db/query-impexp.js')
 const queryCluster = require('../db/query-cluster.js')