From 01ebfa44e3d81177d4398b660a974b12524f6c54 Mon Sep 17 00:00:00 2001 From: Paul Robert Lloyd Date: Sun, 10 Dec 2023 23:14:49 +0000 Subject: [PATCH] Lint JSDoc --- components/site-search/site-search.js | 4 ++++ lib/data/eleventy-computed.js | 7 ++----- lib/data/options.js | 1 - lib/events/generate-govuk-assets.js | 3 +-- lib/filters/date.js | 6 ++---- lib/filters/includes.js | 1 - lib/filters/items-from-collection.js | 3 +-- lib/filters/items-from-navigation.js | 7 +++---- lib/filters/items-from-pagination.js | 3 +-- lib/filters/markdown.js | 4 +--- lib/filters/no-orphans.js | 6 ++---- lib/filters/pretty.js | 4 +--- lib/filters/smart.js | 8 +++----- lib/filters/tokenize.js | 5 ++--- lib/markdown-it.js | 6 ++---- lib/markdown-it/deflist.js | 2 -- lib/markdown-it/footnote.js | 2 -- lib/markdown-it/table-of-contents.js | 2 -- lib/markdown-it/table.js | 2 -- lib/nunjucks.js | 9 +++------ lib/utils.js | 12 +++++------- 21 files changed, 33 insertions(+), 64 deletions(-) diff --git a/components/site-search/site-search.js b/components/site-search/site-search.js index 07534d13..42da7ee3 100644 --- a/components/site-search/site-search.js +++ b/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 } diff --git a/lib/data/eleventy-computed.js b/lib/data/eleventy-computed.js index 2a951b7f..6fdc9957 100644 --- a/lib/data/eleventy-computed.js +++ b/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 = { diff --git a/lib/data/options.js b/lib/data/options.js index a781108d..96646cb8 100644 --- a/lib/data/options.js +++ b/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 = { diff --git a/lib/events/generate-govuk-assets.js b/lib/events/generate-govuk-assets.js index 2d8a573c..8b36ec19 100644 --- a/lib/events/generate-govuk-assets.js +++ b/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 diff --git a/lib/filters/date.js b/lib/filters/date.js index 97b0c2aa..6a5179da 100644 --- a/lib/filters/date.js +++ b/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 diff --git a/lib/filters/includes.js b/lib/filters/includes.js index 89b2280a..076a6100 100644 --- a/lib/filters/includes.js +++ b/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 diff --git a/lib/filters/items-from-collection.js b/lib/filters/items-from-collection.js index 609ac44f..7b6cf4ed 100644 --- a/lib/filters/items-from-collection.js +++ b/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 => ({ diff --git a/lib/filters/items-from-navigation.js b/lib/filters/items-from-navigation.js index 125f35ef..2baf5268 100644 --- a/lib/filters/items-from-navigation.js +++ b/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 || '/' diff --git a/lib/filters/items-from-pagination.js b/lib/filters/items-from-pagination.js index 1e62ca0a..f982ae3c 100644 --- a/lib/filters/items-from-pagination.js +++ b/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 = [] diff --git a/lib/filters/markdown.js b/lib/filters/markdown.js index 61726ed9..6377594c 100644 --- a/lib/filters/markdown.js +++ b/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, '') diff --git a/lib/filters/no-orphans.js b/lib/filters/no-orphans.js index 8d07f1aa..0259612c 100644 --- a/lib/filters/no-orphans.js +++ b/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, '') diff --git a/lib/filters/pretty.js b/lib/filters/pretty.js index 953f2895..29031542 100644 --- a/lib/filters/pretty.js +++ b/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) diff --git a/lib/filters/smart.js b/lib/filters/smart.js index 0f24ef88..7d7f1bbb 100644 --- a/lib/filters/smart.js +++ b/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, '') diff --git a/lib/filters/tokenize.js b/lib/filters/tokenize.js index c6148114..7701dcec 100644 --- a/lib/filters/tokenize.js +++ b/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) diff --git a/lib/markdown-it.js b/lib/markdown-it.js index 6261b529..d2fcd47a 100644 --- a/lib/markdown-it.js +++ b/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 = { diff --git a/lib/markdown-it/deflist.js b/lib/markdown-it/deflist.js index 7762af3b..b2f154d1 100644 --- a/lib/markdown-it/deflist.js +++ b/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 diff --git a/lib/markdown-it/footnote.js b/lib/markdown-it/footnote.js index e0c50e19..468964d8 100644 --- a/lib/markdown-it/footnote.js +++ b/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 diff --git a/lib/markdown-it/table-of-contents.js b/lib/markdown-it/table-of-contents.js index bea30a6a..0f424ceb 100644 --- a/lib/markdown-it/table-of-contents.js +++ b/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 diff --git a/lib/markdown-it/table.js b/lib/markdown-it/table.js index f80ba5b4..27af9fc1 100644 --- a/lib/markdown-it/table.js +++ b/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 diff --git a/lib/nunjucks.js b/lib/nunjucks.js index 2b37b92e..00860507 100644 --- a/lib/nunjucks.js +++ b/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 diff --git a/lib/utils.js b/lib/utils.js index 942aa5e9..520fb6db 100644 --- a/lib/utils.js +++ b/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) {