Ensure JSDoc blocks for tooling are complete

All blocks are documented with a description, params, optional return (or throws) types and “this” where instantiated or bound

babel.config.js

@@ -1,3 +1,8 @@
+/**
+ * Babel config
+ *
+ * @type {import('@babel/core').ConfigFunction}
+ */
 module.exports = function (api) {
   const browserslistEnv = !api.env('test')
     ? 'production'

config/jest/browser/open.mjs

@@ -5,7 +5,7 @@ import serverStart from '../server/start.mjs'
 /**
  * Open browser
  *
- * @param {import('jest').Config} jestConfig
+ * @param {import('jest').Config} jestConfig - Jest config
  */
 export default async function browserOpen (jestConfig) {
   const { maxWorkers } = jestConfig

lib/file-helper.js

@@ -20,7 +20,7 @@ const cache = global.cache || {}
 /**
  * Directory listing for path
  *
- * @param {string} directoryPath
+ * @param {string} directoryPath - Path to directory
  * @param {string} [pattern] - Minimatch pattern
  * @param {import('glob').IOptions} [options] - Glob options
  * @returns {Promise<string[]>} File paths
@@ -43,7 +43,7 @@ const getListing = async (directoryPath, pattern = '**/*', options = {}) => {
 /**
  * Directory listing (directories only)
  *
- * @param {string} directoryPath
+ * @param {string} directoryPath - Path to directory
  * @returns {Promise<string[]>} File paths
  */
 const getDirectories = (directoryPath) => {

lib/jest-helpers.js

@@ -22,7 +22,7 @@ const nunjucksEnv = nunjucks.configure([join(configPaths.src, 'govuk'), configPa
 /**
  * Render the raw HTML for a component
  *
- * @param {string} componentName
+ * @param {string} componentName - Component name
  * @param {object} options - options to pass to the component macro
  * @param {string} [callBlock] - if provided, the macro is called using the
  *   Nunjucks call tag, with the callBlock passed as the contents of the block
@@ -71,7 +71,7 @@ function callMacro (macroName, macroPath, params = [], callBlock = false) {
  *
  * Allows us to interrogate the output of the macro using a jQuery-like syntax
  *
- * @param {string} componentName
+ * @param {string} componentName - Component name
  * @param {object} options - options to pass to the component macro
  * @param {string} [callBlock] - if provided, the macro is called using the
  *   Nunjucks call tag, with the callBlock passed as the contents of the block
@@ -83,7 +83,14 @@ function render (componentName, options, callBlock = false) {
   )
 }
 
-function renderTemplate (params = {}, blocks = {}) {
+/**
+ * Render Nunjucks template into Cheerio API
+ *
+ * @param {object} [context] - Nunjucks context
+ * @param {Object<string, string>} [blocks] - Nunjucks blocks
+ * @returns {import('cheerio').CheerioAPI} a jQuery-like representation of the template output
+ */
+function renderTemplate (context = {}, blocks = {}) {
   let viewString = '{% extends "template.njk" %}'
 
   for (const [blockName, blockContent] of Object.entries(blocks)) {
@@ -94,15 +101,15 @@ function renderTemplate (params = {}, blocks = {}) {
       {%- endblock %}`
   }
 
-  const output = nunjucksEnv.renderString(viewString, params)
+  const output = nunjucksEnv.renderString(viewString, context)
   return cheerio.load(output)
 }
 
 /**
  * Get examples from a component's metadata file
  *
- * @param {string} componentName
- * @returns {object} returns object that includes all examples at once
+ * @param {string} componentName - Component name
+ * @returns {Promise<Object<string, object>>} returns object that includes all examples at once
  */
 async function getExamples (componentName) {
   const componentData = await getComponentData(componentName)

lib/puppeteer-helpers.js

@@ -19,7 +19,7 @@ const PORT = process.env.PORT || configPaths.ports.test
  *
  * @param {import('puppeteer').Page} page - Puppeteer page object
  * @param {string} componentName - The kebab-cased name of the component
- * @param {object} options
+ * @param {object} options - Render and initialise options
  * @param {object} options.nunjucksParams - Params passed to the Nunjucks macro
  * @param {object} [options.javascriptConfig] - The configuration hash passed to
  *  the component's class for initialisation

postcss.config.js

@@ -14,7 +14,7 @@ const unrgba = require('postcss-unrgba')
  * @param {object} context - PostCSS context
  * @param {string} context.env - Browserslist environment
  * @param {string | import('vinyl')} [context.file] - File path or object
- * @returns {{ plugins: import('postcss').Transformer[] }} PostCSS config
+ * @returns {import('postcss-load-config').Config} PostCSS config
  */
 module.exports = ({ env, file = '' }) => {
   const { dir, name } = parse(typeof file === 'object'

tasks/clean.mjs

@@ -7,6 +7,12 @@ import { destination } from './task-arguments.mjs'
 
 const cleanPath = slash(destination)
 
+/**
+ * List path globs to clean for a given destination
+ *
+ * @param {string} cleanPath - Destination path to clean
+ * @returns {string[]} Path globs to clean
+ */
 export function paths (cleanPath) {
   const param = [slash(join(cleanPath, '**/*'))]
 

tasks/gulp/compile-assets.mjs

@@ -197,6 +197,7 @@ function compileJavaScript (stream, moduleName) {
  * and logs custom errors from Gulp plugins where available
  *
  * @param {import('stream').Stream} stream - Input file stream
+ * @param {string} name - Task name for non-plugin error logging
  * @returns {import('stream').Stream} Output file stream
  */
 function errorHandler (stream, name) {