Skip to content

Commit

Permalink
Fix JSDoc comments for all/common/i18n
Browse files Browse the repository at this point in the history
  • Loading branch information
@colinrotherham
colinrotherham committed Oct 12, 2022
1 parent 7617d26 commit 171935d
Show file tree
Hide file tree
Showing 3 changed files with 61 additions and 49 deletions.
14 changes: 7 additions & 7 deletions src/govuk/all.mjs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 : {}
Expand Down
50 changes: 31 additions & 19 deletions src/govuk/common.mjs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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()
Expand All @@ -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 = {}
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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') {
Expand Down Expand Up @@ -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 = {}
Expand All @@ -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 + ']')
Expand Down
46 changes: 23 additions & 23 deletions src/govuk/i18n.mjs
View file
Original file line number Diff line number Diff line change
@@ -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 || {}
Expand All @@ -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) {
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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))
Expand All @@ -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))
Expand All @@ -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
Expand Down Expand Up @@ -204,15 +204,15 @@ I18n.prototype.getPluralSuffix = function (count) {
*
* Arabic: Arabic (ar)
* Chinese: Burmese (my), Chinese (zh), Indonesian (id), Japanese (ja),
* Javanese (jv), Korean (ko), Malay (ms), Thai (th), Vietnamese (vi)
* Javanese (jv), Korean (ko), Malay (ms), Thai (th), Vietnamese (vi)
* French: Armenian (hy), Bangla (bn), French (fr), Gujarati (gu), Hindi (hi),
* Persian Farsi (fa), Punjabi (pa), Zulu (zu)
* Persian Farsi (fa), Punjabi (pa), Zulu (zu)
* German: Afrikaans (af), Albanian (sq), Azerbaijani (az), Basque (eu),
* Bulgarian (bg), Catalan (ca), Danish (da), Dutch (nl), English (en),
* Estonian (et), Finnish (fi), Georgian (ka), German (de), Greek (el),
* Hungarian (hu), Luxembourgish (lb), Norwegian (no), Somali (so),
* Swahili (sw), Swedish (sv), Tamil (ta), Telugu (te), Turkish (tr),
* Urdu (ur)
* Bulgarian (bg), Catalan (ca), Danish (da), Dutch (nl), English (en),
* Estonian (et), Finnish (fi), Georgian (ka), German (de), Greek (el),
* Hungarian (hu), Luxembourgish (lb), Norwegian (no), Somali (so),
* Swahili (sw), Swedish (sv), Tamil (ta), Telugu (te), Turkish (tr),
* Urdu (ur)
* Irish: Irish Gaelic (ga)
* Russian: Russian (ru), Ukrainian (uk)
* Scottish: Scottish Gaelic (gd)
Expand Down Expand Up @@ -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) {
Expand Down

0 comments on commit 171935d

Please sign in to comment.