Fix JSDOC's lint required params and returns

.eslintrc.js

@@ -36,9 +36,16 @@ module.exports = {
     'arrow-body-style': ['error', 'always'],
     'import/extensions': ['error', 'always'],
     strict: ['error', 'global'],
+    'jsdoc/require-jsdoc': ['warn', {
+      publicOnly: true
+    }],
     'jsdoc/require-description': 'warn',
-    'jsdoc/require-param': 'warn',
-    'jsdoc/require-returns': 'warn',
+    'jsdoc/require-param': ['warn', {
+      exemptedBy: ['private']
+    }],
+    'jsdoc/require-returns': ['warn', {
+      publicOnly: true
+    }],
     'jsdoc/check-tag-names': 'warn',
     'jsdoc/check-alignment': 'warn',
     'jsdoc/newline-after-description': 'off', // does not work with 'use strict'

app/controllers/import.controller.js

@@ -1,14 +1,15 @@
 'use strict'
 
+/**
+ * Controller for /import
+ * @module ImportController
+ */
+
 const Boom = require('@hapi/boom')
 
 const FeatureFlags = require('../../config/feature-flags.config.js')
 const LegacyImportLicenceService = require('../services/import/legacy-licence.service.js')
 
-/**
- * Controller for /import
- * @module ImportController
- */
 async function licence (request, h) {
   try {
     const { licenceRef } = request.payload

app/controllers/jobs.controller.js

@@ -14,6 +14,8 @@ const ProcessTimeLimitedLicencesService = require('../services/jobs/time-limited
  * Triggers export of all relevant tables to CSV and then uploads them to S3
  *
  * > Has to be called something other than 'export' because export is a reserved word
+ *
+ * @returns {Promise<object>} - A promise that resolves to an HTTP response object with a 204 status code
  */
 async function exportDb (_request, h) {
   ExportService.go()

app/services/health/create-redis-client.service.js

@@ -11,6 +11,8 @@ const redisConfig = require('../../../config/redis.config.js')
 
 /**
  * Connect to Redis and return a client
+ *
+ * @returns {Promise<Redis>} - a new redis instance
 */
 async function go () {
   return new Redis({

app/services/health/fetch-import-jobs.service.js

@@ -9,6 +9,8 @@ const { db } = require('../../../db/db.js')
 
 /**
  * Returns data required to populate the Import tasks of our `/health/info` page.
+ *
+ * @returns {object} - query response
 */
 async function go () {
   const PGBOSS_JOBS_ARRAY = [

app/services/plugins/payload-cleaning.service.js

@@ -74,6 +74,8 @@ const Sanitizer = require('sanitizer')
  * So we created this service which is used by the `PayLoadCleanerPlugin` to 'clean' incoming requests.
  *
  * * @module ObjectCleaningService
+ *
+ * @returns {object} - returns a 'clean' payload object
  */
 function go (payload) {
   return _cleanObject(payload)

app/validators/custom/date.validators.js

@@ -7,6 +7,8 @@
 /**
  * Validates a string is in the format yyyy-mm-dd
  *
+ * @returns {string} - returns the string value if the date is a valid ISO date YYYY-MM-DD
+ * @throws {Error} - throws an error if the date is not in the correct format or is not a valid date
  */
 const isValidISODate = (value) => {
   const regex = /^\d{4}-\d{2}-\d{2}$/

test/support/helpers/address.helper.js

@@ -40,6 +40,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/bill-licence.helper.js

@@ -36,6 +36,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/bill-run-charge-version-year.helper.js

@@ -37,6 +37,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/bill-run-volume.helper.js

@@ -36,6 +36,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/bill-run.helper.js

@@ -39,6 +39,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/bill.helper.js

@@ -38,6 +38,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/billing-account-address.helper.js

@@ -35,6 +35,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/billing-account.helper.js

@@ -35,6 +35,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/charge-category.helper.js

@@ -44,6 +44,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/charge-element.helper.js

@@ -48,6 +48,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/charge-reference.helper.js

@@ -49,6 +49,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/charge-version-note.helper.js

@@ -34,6 +34,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/charge-version.helper.js

@@ -42,6 +42,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/company-address.helper.js

@@ -36,6 +36,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/company-contact.helper.js

@@ -36,6 +36,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/company.helper.js

@@ -36,6 +36,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/contact.helper.js

@@ -36,6 +36,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/event.helper.js

@@ -47,6 +47,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const timestamp = timestampForPostgres()

test/support/helpers/gauging-station.helper.js

@@ -39,6 +39,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const timestamp = timestampForPostgres()

test/support/helpers/licence-agreement.helper.js

@@ -36,6 +36,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/licence-document-header.helper.js

@@ -38,6 +38,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/licence-document-role.helper.js

@@ -37,6 +37,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/licence-document.helper.js

@@ -34,6 +34,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/licence-entity-role.helper.js

@@ -37,6 +37,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/licence-entity.helper.js

@@ -35,6 +35,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/licence-gauging-station.helper.js

@@ -40,6 +40,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/licence-role.helper.js

@@ -33,6 +33,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/licence-supplementary-year.helper.js

@@ -34,6 +34,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here in the database
+ *
+ * @returns {object} - Returns data from the query
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/licence-version-purpose-condition.helper.js

@@ -40,6 +40,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const timestamp = timestampForPostgres()

test/support/helpers/licence-version-purpose.helper.js

@@ -44,6 +44,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const timestamp = timestampForPostgres()

test/support/helpers/licence-version.helper.js

@@ -41,6 +41,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const timestamp = timestampForPostgres()

test/support/helpers/licence.helper.js

@@ -38,6 +38,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const defaults = {

test/support/helpers/mod-log.helper.js

@@ -40,6 +40,8 @@ function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const regionCode = randomInteger(1, 9)

test/support/helpers/permit-licence.helper.js

@@ -37,6 +37,8 @@ async function add (data = {}) {
  * for use in tests to avoid having to duplicate values.
  *
  * @param {object} [data] - Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {object} - Returns the set defaults with the override data spread
  */
 function defaults (data = {}) {
   const licenceRef = data.licenceRef ? data.licenceRef : generateLicenceRef()
@@ -70,6 +72,7 @@ function defaults (data = {}) {
  * This was the NALD dump the legacy acceptance test data loading solution used. It doesn't matter that the data
  * included doesn't match with the related licence and other records. The critical factor is the structure must align
  * with what the legacy apps expect.
+ * @param licenceRef
  */
 function _licenceDataValue (licenceRef) {
   return {