Fix JSDoc comments for all/common/i18n

src/govuk/all.mjs

@@ -18,13 +18,13 @@ import { I18n } from './i18n.mjs'
  * Use the `data-module` attributes to find, instantiate and init all of the
  * components provided as part of GOV.UK Frontend.
  *
- * @param {Object} [config]
- * @param {HTMLElement} [config.scope=document] - scope to query for components
- * @param {Object} [config.accordion] - accordion config
- * @param {Object} [config.button] - button config
- * @param {Object} [config.characterCount] - character count config
- * @param {Object} [config.errorSummary] - error summary config
- * @param {Object} [config.notificationBanner] - notification banner config
+ * @param {object} [config] - Config
+ * @param {HTMLElement} [config.scope=document] - Scope to query for components
+ * @param {object} [config.accordion] - Accordion config
+ * @param {object} [config.button] - Button config
+ * @param {object} [config.characterCount] - Character Count config
+ * @param {object} [config.errorSummary] - Error Summary config
+ * @param {object} [config.notificationBanner] - Notification Banner config
  */
 function initAll (config) {
   config = typeof config !== 'undefined' ? config : {}

src/govuk/common.mjs

@@ -6,6 +6,10 @@ import './vendor/polyfills/Element/prototype/closest.mjs'
  * TODO: Ideally this would be a NodeList.prototype.forEach polyfill
  * This seems to fail in IE8, requires more investigation.
  * See: https://github.com/imagitama/nodelist-foreach-polyfill
+ *
+ * @param {NodeListOf<Element>} nodes - NodeList from querySelectorAll()
+ * @param {(value: Element, key: number, parent: NodeListOf<Element>) => void} callback - Callback function to run for each node
+ * @returns {void}
  */
 export function nodeListForEach (nodes, callback) {
   if (window.NodeList.prototype.forEach) {
@@ -20,6 +24,8 @@ export function nodeListForEach (nodes, callback) {
  * Used to generate a unique string, allows multiple instances of the component
  * without them conflicting with each other.
  * https://stackoverflow.com/a/8809472
+ *
+ * @returns {string} Unique ID
  */
 export function generateUniqueID () {
   var d = new Date().getTime()
@@ -34,18 +40,24 @@ export function generateUniqueID () {
 }
 
 /**
- * Config flattening function. Takes any number of objects, flattens them into
- * namespaced key-value pairs, (e.g. {'i18n.showSection': 'Show section'}) and
- * combines them together, with greatest priority on the LAST item passed in.
+ * Config flattening function
+ *
+ * Takes any number of objects, flattens them into namespaced key-value pairs,
+ * (e.g. {'i18n.showSection': 'Show section'}) and combines them together, with
+ * greatest priority on the LAST item passed in.
  *
- * @param {...Object} - Any number of objects to merge together.
- * @returns {Object} - A flattened object of key-value pairs.
+ * @returns {object} A flattened object of key-value pairs.
  */
-export function mergeConfigs (/* ...config objects */) {
-  // Function to take nested objects and flatten them to a dot-separated keyed
-  // object. Doing this means we don't need to do any deep/recursive merging of
-  // each of our objects, nor transform our dataset from a flat list into a
-  // nested object.
+export function mergeConfigs (/* configObject1, configObject2, ...configObjects */) {
+  /**
+   * Function to take nested objects and flatten them to a dot-separated keyed
+   * object. Doing this means we don't need to do any deep/recursive merging of
+   * each of our objects, nor transform our dataset from a flat list into a
+   * nested object.
+   *
+   * @param {object} configObject - Deeply nested object
+   * @returns {object} Flattened object with dot-separated keys
+   */
   var flattenObject = function (configObject) {
     // Prepare an empty return object
     var flattenedObject = {}
@@ -100,9 +112,9 @@ export function mergeConfigs (/* ...config objects */) {
  * Extracts keys starting with a particular namespace from a flattened config
  * object, removing the namespace in the process.
  *
- * @param {Object} configObject  - The object to extract key-value pairs from.
- * @param {String} namespace     - The namespace to filter keys with.
- * @returns {Object}
+ * @param {object} configObject - The object to extract key-value pairs from.
+ * @param {string} namespace - The namespace to filter keys with.
+ * @returns {object} Flattened object with dot-separated key namespace removed
  */
 export function extractConfigByNamespace (configObject, namespace) {
   // Check we have what we need
@@ -143,8 +155,8 @@ export function extractConfigByNamespace (configObject, namespace) {
  * Designed to be used to convert config passed via data attributes (which are
  * always strings) into something sensible.
  *
- * @param {String} value - The value to normalise
- * @returns {(String|Boolean|Number)} Normalised data
+ * @param {string} value - The value to normalise
+ * @returns {string | boolean | number | undefined} Normalised data
  */
 export function normaliseString (value) {
   if (typeof value !== 'string') {
@@ -175,8 +187,8 @@ export function normaliseString (value) {
  *
  * Loop over an object and normalise each value using normaliseData function
  *
- * @param {DOMStringMap} dataset
- * @returns {Object} Normalised dataset
+ * @param {DOMStringMap} dataset - HTML element dataset
+ * @returns {Object<string, string | boolean | number | undefined>} Normalised dataset
  */
 export function normaliseDataset (dataset) {
   var out = {}
@@ -192,8 +204,8 @@ export function normaliseDataset (dataset) {
  * Returns the value of the given attribute closest to the given element (including itself)
  *
  * @param {HTMLElement} $element - The element to start walking the DOM tree up
- * @param {String} attributeName - The name of the attribute
- * @returns {String|undefined}
+ * @param {string} attributeName - The name of the attribute
+ * @returns {string | null} Attribute value
  */
 export function closestAttributeValue ($element, attributeName) {
   var closestElementWithAttribute = $element.closest('[' + attributeName + ']')

src/govuk/i18n.mjs

@@ -1,10 +1,10 @@
 /**
  * i18n support initialisation function
  *
- * @constructor
- * @param  {Object}  translations   - Key-value pairs of the translation strings to use.
- * @param  {Object}  config         - Configuration options for the function.
- * @param  {String}  config.locale  - An overriding locale for the PluralRules functionality.
+ * @class
+ * @param {object} translations - Key-value pairs of the translation strings to use.
+ * @param {object} config - Configuration options for the function.
+ * @param {string} config.locale - An overriding locale for the PluralRules functionality.
  */
 export function I18n (translations, config) {
   config = config || {}
@@ -20,9 +20,9 @@ export function I18n (translations, config) {
  * The most used function - takes the key for a given piece of UI text and
  * returns the appropriate string.
  *
- * @param    {String}  lookupKey  - The lookup key of the string to use.
- * @param    {Object}  options    - Any options passed with the translation string, e.g: for string interpolation.
- * @returns  {String}             - The appropriate translation string.
+ * @param {string} lookupKey - The lookup key of the string to use.
+ * @param {object} options - Any options passed with the translation string, e.g: for string interpolation.
+ * @returns {string} The appropriate translation string.
  */
 I18n.prototype.t = function (lookupKey, options) {
   if (!lookupKey) {
@@ -75,9 +75,9 @@ I18n.prototype.t = function (lookupKey, options) {
  * Takes a translation string with placeholders, and replaces the placeholders
  * with the provided data
  *
- * @param    {String}  translationString  - The translation string
- * @param    {Object}  options    - Any options passed with the translation string, e.g: for string interpolation.
- * @returns  {String}             - The translation string to output, with ${} placeholders replaced
+ * @param {string} translationString - The translation string
+ * @param {object} options - Any options passed with the translation string, e.g: for string interpolation.
+ * @returns {string} The translation string to output, with ${} placeholders replaced
  */
 I18n.prototype.replacePlaceholders = function (translationString, options) {
   // eslint-disable-next-line prefer-regex-literals
@@ -119,7 +119,7 @@ I18n.prototype.replacePlaceholders = function (translationString, options) {
  * - The implementation of Intl supports PluralRules (NOT true in IE11)
  * - The browser/OS has plural rules for the current locale (browser dependent)
  *
- * @returns  {boolean}  - Returns true if all conditions are met. Returns false otherwise.
+ * @returns {boolean} Returns true if all conditions are met. Returns false otherwise.
  */
 I18n.prototype.hasIntlPluralRulesSupport = function () {
   return Boolean(window.Intl && ('PluralRules' in window.Intl && Intl.PluralRules.supportedLocalesOf(this.locale).length))
@@ -133,7 +133,7 @@ I18n.prototype.hasIntlPluralRulesSupport = function () {
  * - The implementation of Intl supports NumberFormat (also true in IE11)
  * - The browser/OS has number formatting rules for the current locale (browser dependent)
  *
- * @returns  {boolean}  - Returns true if all conditions are met. Returns false otherwise.
+ * @returns {boolean} Returns true if all conditions are met. Returns false otherwise.
  */
 I18n.prototype.hasIntlNumberFormatSupport = function () {
   return Boolean(window.Intl && ('NumberFormat' in window.Intl && Intl.NumberFormat.supportedLocalesOf(this.locale).length))
@@ -147,8 +147,8 @@ I18n.prototype.hasIntlNumberFormatSupport = function () {
  * regardless of region. There are exceptions, however, (e.g. Portuguese) so
  * this searches by both the full and shortened locale codes, just to be sure.
  *
- * @param    {number}  count       - Number used to determine which pluralisation to use.
- * @returns  {string}              - The suffix associated with the correct pluralisation for this locale.
+ * @param {number} count - Number used to determine which pluralisation to use.
+ * @returns {string} The suffix associated with the correct pluralisation for this locale.
  */
 I18n.prototype.getPluralSuffix = function (count) {
   var locale = this.locale
@@ -243,8 +243,8 @@ I18n.prototype.pluralRulesMap = {
  * languages without plurals, such as Chinese.
  * https://unicode-org.github.io/cldr-staging/charts/latest/supplemental/language_plural_rules.html
  *
- * @param    {number}  n  - The `count` number being passed through. This must be a positive integer. Negative numbers and decimals aren't accounted for.
- * @returns  {string}     - The string that needs to be suffixed to the key (without separator).
+ * @param {number} n - The `count` number being passed through. This must be a positive integer. Negative numbers and decimals aren't accounted for.
+ * @returns {string} The string that needs to be suffixed to the key (without separator).
  */
 I18n.prototype.pluralRules = {
   arabic: function (n) {