Housekeeping - second pass of the JSDocs

app/presenters/bill-runs/review/base-review.presenter.js

@@ -102,7 +102,7 @@ function formatChargePeriod (reviewChargeVersion) {
  *
  * @param {module:ReviewChargeElementModel} reviewChargeElement - instance of `ReviewChargeElementModel` containing at
  * least a `chargeElement` property populated with abstraction days and months
- * @param {*} [chargePeriod]
+ * @param {object} [chargePeriod] - The start and end date of the calculated charge period
  *
  * @returns {string[]} an array containing the review charge element's charge period(s) formatted as 'DD MMMM YYYY to DD
  * MMMM YYYY'

app/presenters/bill-runs/review/remove.presenter.js

@@ -13,7 +13,7 @@ const { formatFinancialYear, formatLongDate } = require('../../base.presenter.js
  * @param {module:ReviewLicenceModel} reviewLicence - instance of the `ReviewLicenceModel` returned from
  * `FetchRemoveReviewLicenceService`
  *
- * @returns {object}page date needed for the remove review licence confirmation page
+ * @returns {object} page date needed for the remove review licence confirmation page
  */
 function go (reviewLicence) {
   const { billRun, id: reviewLicenceId, licenceRef } = reviewLicence

app/services/bill-runs/review/fetch-review-charge-element.service.js

@@ -1,7 +1,7 @@
 'use strict'
 
 /**
- * Fetches the selected review charge element instance and related data for the 2PT review charge element page
+ * Fetches the selected review charge element instance and related data for the 2PT review charge element pages
  * @module FetchReviewChargeReferenceService
  */
 
@@ -10,11 +10,14 @@ const { ref } = require('objection')
 const ReviewChargeElementModel = require('../../../models/review-charge-element.model.js')
 
 /**
- * Fetches the match details for an individual charge element
+ * Fetches the selected review charge element instance and related data for the 2PT review charge element pages
+ *
+ * This fetch service fetches the data needed for the main review charge element page, but also the edit page/service.
  *
  * @param {string} reviewChargeElementId - The UUID of the review charge element being viewed
  *
- * @returns {Promise<object>} An object containing the bill run and review charge element instances
+ * @returns {Promise<object>} the matching `ReviewChargeElementModel` instance and related data needed for the
+ * two-part tariff review charge element page
  */
 async function go (reviewChargeElementId) {
   return _fetch(reviewChargeElementId)

app/services/bill-runs/review/submit-review-bill-run.service.js

@@ -11,6 +11,8 @@
  * @param {string} billRunId - The UUID of the bill run
  * @param {object} payload - The `request.payload` containing the filter data.
  * @param {object} yar - The Hapi `request.yar` session manager passed on by the controller
+ *
+ * @returns {Promise<object>} the promise returned is not intended to resolve to any particular value
  */
 async function go (billRunId, payload, yar) {
   const clearFilters = payload?.clearFilters

app/validators/bill-runs/review/edit.validator.js

@@ -14,6 +14,7 @@ const Joi = require('joi')
  * there own custom volume. The validation happening here is to ensure that a user selects either option and if its the
  * custom one, that they enter a number above 0 but below the authorised volume and that the number is less than 6
  * decimal places.
+ *
  * @param {object} payload - The payload from the request to be validated
  *
  * @returns {object} the result from calling Joi's schema.validate(). It will be an object with a `value:` property. If

app/validators/bill-runs/review/factors.validator.js

@@ -10,6 +10,9 @@ const Joi = require('joi')
 /**
  * Validates data submitted for the review charge reference factors page
  *
+ * There are two inputs on the page, both of which need to contain valid values. However, they are always pre-populated
+ * with existing data, so in theory would only both be invalid if the user has incorrectly updated both.
+ *
  * @param {object} payload - The payload from the request to be validated
  *
  * @returns {object} The result from calling Joi's schema.validate(). If any errors are found the `error:` property will