feat: adopt jsdoc for internal docs

This adopts jsdoc as cve-services' mechanism for internal
API documentation. This mostly means annotating modules,
but not actually writing documentation for them, except for
the new authz middleware which is the initial test case.

One of the challenges I've had since joining the CVE Services
team has been discovering and understanding the internal
structure of the codebase, and this is in part my attempt to
help ease that problem for others.

Signed-off-by: Andrew Lilley Brinker <abrinker@mitre.org>

Author: alilleybrinker

src/constants/index.js

@@ -1,3 +1,7 @@
+/**
+ * @module constants
+ */
+
 const fs = require('fs')
 const cveSchemaV5 = JSON.parse(fs.readFileSync('src/middleware/schemas/CVE_JSON_5.2.0_bundled.json'))
 
@@ -8,6 +12,7 @@ const cveSchemaV5 = JSON.parse(fs.readFileSync('src/middleware/schemas/CVE_JSON_
  * value re-assignment and still allow IDE type-hints and compiled regex
  *
  * @return {defaults}
+ * @alias module:constants.getConstants
  */
 function getConstants () {
   /**

src/controller/audit.controller/audit.controller.js

@@ -1,3 +1,7 @@
+/**
+ * @module controller/audit/controller
+ */
+
 const mongoose = require('mongoose')
 const logger = require('../../middleware/logger')
 const errors = require('./error')

src/controller/audit.controller/audit.middleware.js

@@ -1,3 +1,7 @@
+/**
+* @module controller/audit/middleware
+ */
+
 const utils = require('../../utils/utils')
 
 /**

src/controller/audit.controller/error.js

@@ -1,3 +1,7 @@
+/**
+ * @module controller/audit/error
+ */
+
 const idrErr = require('../../utils/error')
 
 class AuditControllerError extends idrErr.IDRError {

src/controller/audit.controller/index.js

@@ -1,3 +1,7 @@
+/**
+ * @module controller/audit
+ */
+
 const router = require('express').Router()
 const controller = require('./audit.controller')
 const mw = require('../../middleware/middleware')

src/controller/conversation.controller/conversation.controller.js

@@ -1,3 +1,7 @@
+/**
+ * @module controller/conversation/controller
+ */
+
 const mongoose = require('mongoose')
 const logger = require('../../middleware/logger')
 const getConstants = require('../../../src/constants').getConstants

src/controller/conversation.controller/index.js

@@ -1,3 +1,7 @@
+/**
+ * @module controller/conversation
+ */
+
 const router = require('express').Router()
 const { param, query } = require('express-validator')
 const controller = require('./conversation.controller')

src/controller/cve-id.controller/cve-id.controller.js

@@ -1,3 +1,7 @@
+/**
+ * @module controller/cve-id/controller
+ */
+
 require('dotenv').config()
 const CveId = require('../../model/cve-id')
 const logger = require('../../middleware/logger')

src/controller/cve-id.controller/cve-id.middleware.js

@@ -1,3 +1,7 @@
+/**
+ * @module controller/cve-id/middleware
+ */
+
 const { validationResult } = require('express-validator')
 const errors = require('./error')
 const error = new errors.CveIdControllerError()

src/controller/cve-id.controller/error.js

@@ -1,3 +1,7 @@
+/**
+ * @module controller/cve-id/error
+ */
+
 const idrErr = require('../../utils/error')
 const getConstants = require('../../constants').getConstants