From 03896ff1eaa81dc3ef9dc4afde268a43fabc2204 Mon Sep 17 00:00:00 2001 From: Alan Cruikshanks Date: Thu, 7 Nov 2024 10:10:01 +0000 Subject: [PATCH] Housekeeping - second pass of the JSDocs --- app/presenters/bill-runs/review/base-review.presenter.js | 2 +- app/presenters/bill-runs/review/remove.presenter.js | 2 +- .../review/fetch-review-charge-element.service.js | 9 ++++++--- .../bill-runs/review/submit-review-bill-run.service.js | 2 ++ app/validators/bill-runs/review/edit.validator.js | 1 + app/validators/bill-runs/review/factors.validator.js | 3 +++ 6 files changed, 14 insertions(+), 5 deletions(-) diff --git a/app/presenters/bill-runs/review/base-review.presenter.js b/app/presenters/bill-runs/review/base-review.presenter.js index 38426a611..cf5048ec8 100644 --- a/app/presenters/bill-runs/review/base-review.presenter.js +++ b/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' diff --git a/app/presenters/bill-runs/review/remove.presenter.js b/app/presenters/bill-runs/review/remove.presenter.js index d26197af1..c44e9800b 100644 --- a/app/presenters/bill-runs/review/remove.presenter.js +++ b/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 diff --git a/app/services/bill-runs/review/fetch-review-charge-element.service.js b/app/services/bill-runs/review/fetch-review-charge-element.service.js index c9ba3ed90..a5912e1fc 100644 --- a/app/services/bill-runs/review/fetch-review-charge-element.service.js +++ b/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} An object containing the bill run and review charge element instances + * @returns {Promise} the matching `ReviewChargeElementModel` instance and related data needed for the + * two-part tariff review charge element page */ async function go (reviewChargeElementId) { return _fetch(reviewChargeElementId) diff --git a/app/services/bill-runs/review/submit-review-bill-run.service.js b/app/services/bill-runs/review/submit-review-bill-run.service.js index f5ac10a68..15a183870 100644 --- a/app/services/bill-runs/review/submit-review-bill-run.service.js +++ b/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} the promise returned is not intended to resolve to any particular value */ async function go (billRunId, payload, yar) { const clearFilters = payload?.clearFilters diff --git a/app/validators/bill-runs/review/edit.validator.js b/app/validators/bill-runs/review/edit.validator.js index 4ba3717e2..f68d61d4f 100644 --- a/app/validators/bill-runs/review/edit.validator.js +++ b/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 diff --git a/app/validators/bill-runs/review/factors.validator.js b/app/validators/bill-runs/review/factors.validator.js index 40429e3ba..17203f48d 100644 --- a/app/validators/bill-runs/review/factors.validator.js +++ b/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