Fix JSDoc formatting etc

Author: colinrotherham

app/filters.js

@@ -9,7 +9,8 @@ module.exports = function (env) {
    * Instantiate object used to store the methods registered as a
    * 'filter' (of the same name) within nunjucks. You can override
    * gov.uk core filters by creating filter methods of the same name.
-   * @type {Object}
+   *
+   * @type {object}
    */
   const filters = {}
 

app/filters/form-attributes.js

@@ -7,11 +7,10 @@ const _ = require('lodash')
  * Add name, value, id, idPrefix and checked attributes to NHSUK form components
  * Generate the attributes based on the application ID and the section they're in
  *
- * @param {Object} originalObject - The original component configuration
- * @param {Object} data - The data object to extract values from
+ * @param {object} originalObject - The original component configuration
+ * @param {object} data - The data object to extract values from
  * @param {string} path - Path to the data property (e.g. "data.nationality")
- * @returns {Object} The decorated component configuration
- *
+ * @returns {object} The decorated component configuration
  * @example
  * {{ nhsukCheckboxes({
  *   fieldset: {

app/filters/formatting.js

@@ -2,12 +2,13 @@
 
 /**
  * Format a yes/no/not answered response with optional additional details
+ *
  * @param {string|boolean} value - The response value to format
- * @param {Object} [options] - Formatting options
+ * @param {object} [options] - Formatting options
  * @param {string} [options.yesValue] - Additional details to show after "Yes -" for positive responses
- * @param {string} [options.noText="No"] - Text to show for negative responses
- * @param {string} [options.notAnsweredText="Not answered"] - Text to show when no response given
- * @param {string} [options.yesPrefix="Yes"] - Text to show for positive responses (before any yesValue)
+ * @param {string} [options.noText] - Text to show for negative responses
+ * @param {string} [options.notAnsweredText] - Text to show when no response given
+ * @param {string} [options.yesPrefix] - Text to show for positive responses (before any yesValue)
  * @returns {string} Formatted response text
  * @example
  * formatAnswer("yes", { yesValue: "Details here" }) // Returns "Yes - Details here"

app/filters/forms.js

@@ -2,9 +2,9 @@
 
 /**
  * Add error messages to form components based on flash messages
- * @param {Object} component - The form component configuration object
- * @param {Object} context - The template context containing flash messages
- * @returns {Object} Updated component configuration with error details if applicable
+ *
+ * @param {object} component - The form component configuration object
+ * @returns {object} Updated component configuration with error details if applicable
  */
 const populateErrors = function (component) {
   // Get flash messages from template context

app/filters/nunjucks.js

@@ -14,14 +14,14 @@ const log = (a, description = null) => {
 
 /**
  * Safely join array elements with proper undefined/null handling
+ *
  * @param {any} input - Array-like input to join
- * @param {string} [delimiter=''] - String to use as delimiter between elements
- * @param {string} [attribute] - Optional object property to extract before joining
- * @param {Object} [options] - Additional options for join behavior
- * @param {boolean} [options.filterEmpty=true] - Whether to filter out empty/null/undefined values
- * @param {boolean} [options.toString=true] - Whether to convert values to strings before joining
+ * @param {string} [delimiter] - String to use as delimiter between elements
+ * @param {string | null} [attribute] - Optional object property to extract before joining
+ * @param {object} [options] - Additional options for join behavior
+ * @param {boolean} [options.filterEmpty] - Whether to filter out empty/null/undefined values
+ * @param {boolean} [options.toString] - Whether to convert values to strings before joining
  * @returns {string} Joined string or empty string if invalid input
- *
  * @example
  * join(['a', 'b', 'c'], ', ') // 'a, b, c'
  * join([{name: 'John'}, {name: 'Jane'}], ', ', 'name') // 'John, Jane'
@@ -86,10 +86,11 @@ const join = (input, delimiter = '', attribute = null, options = {}) => {
 
 /**
  * Get user name by user ID with format options
+ *
  * @param {string} userId - ID of the user
- * @param {Object} options - Display options
- * @param {boolean} [options.identifyCurrentUser=false] - Whether to add "(you)" for current user
- * @param {string} [options.format='full'] - Name format: 'full', 'short', or 'initial'
+ * @param {object} [options] - Display options
+ * @param {boolean} [options.identifyCurrentUser] - Whether to add "(you)" for current user
+ * @param {string} [options.format] - Name format: 'full', 'short', or 'initial'
  * @returns {string} User's name in requested format
  */
 const getUsername = function (userId, options = {}) {
@@ -127,7 +128,7 @@ const getUsername = function (userId, options = {}) {
 
 /**
  *
- * @returns {Object} The context data
+ * @returns {object} The context data
  */
 const getContext = function () {
   return this.ctx

app/filters/tags.js

@@ -6,8 +6,9 @@ const { getStatusTagColour, getStatusText } = require('../lib/utils/status')
 
 /**
  * Convert a status string into an NHS tag
+ *
  * @param {string} status - Status to convert
- * @param {Object} [options] - Optional configuration
+ * @param {object} [options] - Optional configuration
  * @returns {string} HTML for tag component
  */
 const toTag = (status, options = {}) => {

app/lib/generators/address-generator.js

@@ -69,6 +69,7 @@ const HOUSE_NAMES = [
 
 /**
  * Extract postcode area (first 1-2 letters) from a full postcode
+ *
  * @param {string} postcode - Full UK postcode
  * @returns {string} Postcode area (e.g., 'OX' from 'OX3 7LE')
  */
@@ -78,6 +79,7 @@ const getPostcodeArea = (postcode) => {
 
 /**
  * Get the postcode district (number after area) from a full postcode
+ *
  * @param {string} postcode - Full UK postcode
  * @returns {string} Postcode district number
  */
@@ -87,6 +89,7 @@ const getPostcodeDistrict = (postcode) => {
 
 /**
  * Generate a random postcode in the same area as the reference postcode
+ *
  * @param {string} referencePostcode - Postcode to base the new one on
  * @returns {string} New postcode in same area
  */
@@ -113,6 +116,7 @@ const generateNearbyPostcode = (referencePostcode) => {
 
 /**
  * Generate a random street name
+ *
  * @returns {string} Generated street name
  */
 const generateStreetName = () => {
@@ -123,7 +127,8 @@ const generateStreetName = () => {
 
 /**
  * Generate line 1 of an address
- * @returns {Object} Address line 1 details
+ *
+ * @returns {object} Address line 1 details
  */
 const generateAddressLine1 = () => {
   // 20% chance of using a house name instead of number
@@ -151,7 +156,8 @@ const generateAddressLine1 = () => {
 
 /**
  * Generate list of nearby towns/areas based on BSU location
- * @param {Object} bsu - Breast screening unit object
+ *
+ * @param {object} bsu - Breast screening unit object
  * @returns {Array} List of nearby towns/areas
  */
 const generateNearbyAreas = (bsu) => {
@@ -192,8 +198,9 @@ const generateNearbyAreas = (bsu) => {
 
 /**
  * Generate an address appropriate for the BSU area
- * @param {Object} bsu - Breast screening unit object
- * @returns {Object} Generated address object
+ *
+ * @param {object} bsu - Breast screening unit object
+ * @returns {object} Generated address object
  */
 const generateBSUAppropriateAddress = (bsu) => {
   const nearbyAreas = generateNearbyAreas(bsu)

app/lib/generators/mammogram-generator.js

@@ -48,15 +48,16 @@ const generateImageUrl = (side, view, accessionNumber) => {
 
 /**
  * Generate images for a single view
- * @param {Object} params - Parameters for image generation
+ *
+ * @param {object} params - Parameters for image generation
  * @param {string} params.side - Breast side ('right' or 'left')
  * @param {string} params.view - View type ('mediolateral oblique' or 'craniocaudal')
  * @param {string} params.accessionBase - Base accession number
  * @param {number} params.startIndex - Starting index for image numbering
  * @param {string} params.startTime - Start timestamp
  * @param {boolean} params.isSeedData - Whether generating seed data
  * @param {boolean} [params.needsRepeat] - Force this view to be repeated
- * @returns {Object} View data with images
+ * @returns {object} View data with images
  */
 const generateViewImages = ({
   side,
@@ -109,14 +110,15 @@ const generateViewImages = ({
 
 /**
  * Generate a complete set of mammogram images
- * @param {Object} options - Generation options
+ *
+ * @param {object} [options] - Generation options
  * @param {Date|string} [options.startTime] - Starting timestamp (defaults to now)
- * @param {boolean} [options.isSeedData=false] - Whether generating seed data
- * @param {Object} [options.config] - Optional configuration for specific scenarios
+ * @param {boolean} [options.isSeedData] - Whether generating seed data
+ * @param {object} [options.config] - Optional configuration for specific scenarios
  * @param {string[]} [options.config.repeatViews] - Array of views to repeat (e.g. ['RMLO', 'LCC'])
  * @param {string[]} [options.config.missingViews] - Array of views to omit (e.g. ['RMLO'])
- * @param {Object} [options.probabilities] - Override default probabilities
- * @returns {Object} Complete mammogram data
+ * @param {object} [options.probabilities] - Override default probabilities
+ * @returns {object} Complete mammogram data
  */
 const generateMammogramImages = ({
   startTime = new Date(),

app/lib/generators/participant-generator.js

@@ -10,9 +10,9 @@ const dayjs = require('dayjs')
 
 /**
  * Generate a precise date of birth within the specified age range
- * @param {Object} options - Generation options
- * @param {string} options.riskLevel - Risk level to use for age range
- * @param {Date} [options.referenceDate] - Date to calculate age from (defaults to today)
+ *
+ * @param {string} riskLevel - Risk level to use for age range
+ * @param {Date} [referenceDate] - Date to calculate age from (defaults to today)
  * @returns {string} ISO date string for date of birth
  */
 const generateDateOfBirth = (riskLevel, referenceDate = new Date()) => {

app/lib/generators/reading-generator.js

@@ -6,6 +6,7 @@ const { eligibleForReading } = require('../utils/status')
 
 /**
  * Generate sample image reading data to simulate first and second reads
+ *
  * @param {Array} events - Array of screening events
  * @param {Array} users - Array of system users
  * @returns {Array} Updated events with reading data