Lint JSDoc

components/site-search/site-search.js

@@ -11,6 +11,10 @@ let searchQuery = ''
 let searchCallback = function () {}
 let searchResults = []
 
+/**
+ * Get module
+ * @param {string} $module - Module name
+ */
 export function Search ($module) {
   this.$module = $module
 }

lib/data/eleventy-computed.js

@@ -1,8 +1,7 @@
 /**
  * Get navigation key for page
- *
  * @param {object} data Page data
- * @returns {string}
+ * @returns {string|undefined} Page navigation key
  */
 const getKey = (data) => {
   const { homepage, eleventyExcludeFromCollections, eleventyNavigation } = data
@@ -18,9 +17,8 @@ const getKey = (data) => {
 
 /**
  * Get navigation parent for page
- *
  * @param {object} data Page data
- * @returns {string}
+ * @returns {string|undefined} Parent page key
  */
 const getParent = (data) => {
   const { homepage, eleventyExcludeFromCollections, eleventyNavigation } = data
@@ -36,7 +34,6 @@ const getParent = (data) => {
 
 /**
  * Set sensible defaults for eleventyNavigation
- *
  * @see {@link https://www.11ty.dev/docs/plugins/navigation/}
  */
 module.exports = {

lib/data/options.js

@@ -2,7 +2,6 @@ const deepmerge = require('deepmerge')
 
 /**
  * Default option values
- *
  * @see {@link https://x-govuk.github.io/govuk-eleventy-plugin/options/}
  */
 const defaultOptions = {

lib/events/generate-govuk-assets.js

@@ -8,11 +8,10 @@ const { ensureSlash } = require('../utils.js')
 
 /**
  * Generate GOV.UK Frontend assets
- *
  * @param {object} dir - Project directories
  * @param {object} pathPrefix - Path prefix
  * @param {object} options - Plugin options
- * @returns {function}
+ * @returns {Function} Eleventy event
  */
 module.exports = async function (dir, pathPrefix, options) {
   const { imagesPath, fontsPath, brandColour, fontFamily } = options

lib/filters/date.js

@@ -2,12 +2,10 @@ const { DateTime } = require('luxon')
 
 /**
  * Format a data using tokens
- *
- * @example date('2022-03-16', 'yyyy') // 2022
- *
  * @param {string} string - Date to convert
  * @param {string} [format] - Optional token-based formatting
- * @return {string} - Formatted date
+ * @returns {string} Formatted date
+ * @example date('2022-03-16', 'yyyy') // 2022
  */
 module.exports = (string, format) => {
   // Enable special `now` value

lib/filters/includes.js

@@ -1,6 +1,5 @@
 /**
  * Select objects in array whose key includes a value
- *
  * @param {Array} array Array to filter
  * @param {string} keyPath Key to inspect
  * @param {string} value Value key needs to include

lib/filters/items-from-collection.js

@@ -3,9 +3,8 @@ const smart = require('./smart.js')
 /**
  * Transform list of posts in a collection to `items` array that can be
  * consumed by GOV.UK Frontend components
- *
  * @param {Array} array - Eleventy collection data
- * @returns {Array} - `items` array
+ * @returns {Array} `items` array
  */
 module.exports = (array) => {
   return array.map(item => ({

lib/filters/items-from-navigation.js

@@ -4,11 +4,10 @@ const smart = require('./smart.js')
 /**
  * Transform Eleventy navigation data to `items` array that can be
  * consumed by GOV.UK Frontend `govukBreadcrumb` component
- *
  * @param {Array} eleventyNavigation - Eleventy navigation data
- * @param {string} [pageUrl=false] - URL of current page
- * @param {object} [options={}] - Plugin options
- * @returns {Array} - `items` array
+ * @param {string} [pageUrl] - URL of current page
+ * @param {object} [options] - Plugin options
+ * @returns {Array} `items` array
  */
 module.exports = (eleventyNavigation, pageUrl = false, options = {}) => {
   const pathPrefix = options?.pathPrefix || '/'

lib/filters/items-from-pagination.js

@@ -1,9 +1,8 @@
 /**
  * Transform Eleventy pagination data to `items` array that can be
  * consumed by GOV.UK Frontend `govukPagination` component
- *
  * @param {Array} pagination - Eleventy pagination data
- * @returns {Array} - `items` array
+ * @returns {Array} `items` array
  */
 module.exports = (pagination) => {
   const items = []

lib/filters/markdown.js

@@ -3,11 +3,9 @@ const { normalise } = require('../utils.js')
 
 /**
  * Convert Markdown into GOV.UK Frontend-compliant HTML
- *
  * @param {string} string - Markdown string
  * @param {string} value - If `inline`, renders HTML without paragraph tags
- * @return {string} - HTML
- *
+ * @returns {string} HTML
  */
 module.exports = (string, value) => {
   string = normalise(string, '')

lib/filters/no-orphans.js

@@ -3,12 +3,10 @@ const { normalise } = require('../utils.js')
 /**
  * Insert non-breaking space between last two words of a string. This prevents
  * an orphaned word appearing by itself at the end of a paragraph.
- *
+ * @param {string} string - Value to transform
+ * @returns {string} `string` with non-breaking space inserted
  * @example
  * noOrphans('Department for Education') // Department for Education
- *
- * @param {string} string - Value to transform
- * @return {string} - `string` with non-breaking space inserted
  */
 module.exports = (string) => {
   string = normalise(string, '')

lib/filters/pretty.js

@@ -1,10 +1,8 @@
 /**
  * Remove (index).html from a string
- *
  * @see {@link https://www.w3.org/Provider/Style/URI.html}
- *
  * @param {string} string - URL, i.e. /page/index.html
- * @return {string} - Permalink URL, i.e. /page/
+ * @returns {string} Permalink URL, i.e. /page/
  */
 module.exports = string => {
   string = String(string)

lib/filters/smart.js

@@ -2,13 +2,11 @@ const { normalise } = require('../utils.js')
 const smartypants = require('smartypants')
 
 /**
- * Convert ASCII punctuation characters into ‘smart’ typographic equivalents.
- *
+ * Convert ASCII punctuation characters into ‘smart’ typographic equivalents
+ * @param {string} string - Value to transform
+ * @returns {string} `string` with smart typographic punctuation
  * @example
  * smart('Her Majesty\'s Government') // Her Majesty’s Government
- *
- * @param {string} string - Value to transform
- * @return {string} - `string` with smart typographic punctuation
  */
 module.exports = (string) => {
   string = normalise(string, '')

lib/filters/tokenize.js

@@ -1,10 +1,9 @@
 /**
  * Reduce size of a string by removing duplicate and common words
  * @see {@link https://www.hawksworx.com/blog/adding-search-to-a-jamstack-site}
- *
  * @param {string} string - Original string
- * @returns {string} - Tokenised string
-*/
+ * @returns {string} Tokenised string
+ */
 module.exports = string => {
   let content = String(string)
 

lib/markdown-it.js

@@ -3,11 +3,9 @@ const anchor = require('markdown-it-anchor')
 
 /**
  * Configure markdown-it
- *
  * @see {@link https://markdown-it.github.io/markdown-it/}
- *
- * @param {object} [options={}] - Plugin options
- * @returns {Function} - markdown-it instance
+ * @param {object} [options] - Plugin options
+ * @returns {Function} markdown-it instance
  */
 module.exports = (options = {}) => {
   const opts = {

lib/markdown-it/deflist.js

@@ -1,8 +1,6 @@
 /**
  * Render a definition list
- *
  * @param {Function} md - markdown-it instance
- * @returns {Function} - markdown-it rendering rules
  */
 module.exports = function defList (md) {
   const { rules } = md.renderer

lib/markdown-it/footnote.js

@@ -1,8 +1,6 @@
 /**
  * Render footnotes
- *
  * @param {Function} md - markdown-it instance
- * @returns {Function} - markdown-it rendering rules
  */
 module.exports = function footnotes (md) {
   const { rules } = md.renderer

lib/markdown-it/table-of-contents.js

@@ -1,8 +1,6 @@
 /**
  * Render a table of contents
- *
  * @param {Function} md - markdown-it instance
- * @returns {Function} - markdown-it rendering rules
  */
 module.exports = function contentsList (md) {
   const { rules } = md.renderer

lib/markdown-it/table.js

@@ -1,8 +1,6 @@
 /**
  * Render a table with `tabindex` to enable keyboard scrolling
- *
  * @param {Function} md - markdown-it instance
- * @returns {Function} - markdown-it rendering rules
  */
 module.exports = function table (md) {
   const { rules } = md.renderer

lib/nunjucks.js

@@ -6,9 +6,8 @@ const Nunjucks = require('nunjucks')
  * If there is a version conflict between a govuk-eleventy-plugin dependency
  * and the host project's dependencies, npm will include the expected version
  * in a nested node_modules folder.
- *
- * @param {string} module
- * @return {string}
+ * @param {string} module - Module name
+ * @returns {string} Path to module
  */
 const resolveNpmModule = (module) => {
   const localPath = `./node_modules/@x-govuk/govuk-eleventy-plugin/node_modules/${module}`
@@ -17,11 +16,9 @@ const resolveNpmModule = (module) => {
 
 /**
  * Configure Nunjucks environment
- *
  * @see {@link https://mozilla.github.io/nunjucks/api.html#environment}
- *
  * @param {object} eleventyConfig - Eleventy config
- * @returns {Function} - Nunjucks environment
+ * @returns {Function} Nunjucks environment
  */
 module.exports = (eleventyConfig) => {
   const { includes, input, layouts } = eleventyConfig.dir

lib/utils.js

@@ -1,9 +1,8 @@
 /**
-  * Ensure string ends with a slash
-  *
-  * @param {string} string - String
-  * @return {string} String ending with a `/`
-  */
+ * Ensure string ends with a slash.
+ * @param {string} string - String
+ * @returns {string} String ending with a `/`
+ */
 const ensureSlash = (string) => {
   if (typeof string !== 'string') {
     throw new TypeError('Input must be a string')
@@ -19,10 +18,9 @@ const ensureSlash = (string) => {
 /**
  * Normalise value provided to a filter. Checks that a given value exists
  * before performing a transformation.
- *
  * @param {*} value - Input value
  * @param {*} defaultValue - Value to fallback to if no value given
- * @returns defaultValue
+ * @returns {*} defaultValue
  */
 const normalise = (value, defaultValue) => {
   if (value === null || value === undefined || value === false) {