From 00cbe242c2f76ba7a7b5044b5518a0ac2e29a842 Mon Sep 17 00:00:00 2001 From: Colin Rotherham Date: Tue, 8 Aug 2023 15:33:18 +0100 Subject: [PATCH 1/4] Use JSDoc tag `@internal` for I18n class --- packages/govuk-frontend/src/govuk/i18n.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/govuk-frontend/src/govuk/i18n.mjs b/packages/govuk-frontend/src/govuk/i18n.mjs index bba9cfc052..c3e454f210 100644 --- a/packages/govuk-frontend/src/govuk/i18n.mjs +++ b/packages/govuk-frontend/src/govuk/i18n.mjs @@ -2,7 +2,7 @@ * Internal support for selecting messages to render, with placeholder * interpolation and locale-aware number formatting and pluralisation * - * @private + * @internal */ export class I18n { translations From d440378c6fbf75aa3ec914c2e86f6d62732a990f Mon Sep 17 00:00:00 2001 From: Colin Rotherham Date: Tue, 8 Aug 2023 15:33:43 +0100 Subject: [PATCH 2/4] Use JSDoc tag `@internal` for I18n class methods MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Since we mock `.hasIntlPluralRulesSupport()` and call `.getPluralSuffix()` in tests (and others) we can’t mark them as `@private` without compiler warnings Ideally we should only test public interfaces --- packages/govuk-frontend/src/govuk/i18n.mjs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/packages/govuk-frontend/src/govuk/i18n.mjs b/packages/govuk-frontend/src/govuk/i18n.mjs index c3e454f210..a0fedb8e0f 100644 --- a/packages/govuk-frontend/src/govuk/i18n.mjs +++ b/packages/govuk-frontend/src/govuk/i18n.mjs @@ -9,6 +9,7 @@ export class I18n { locale /** + * @internal * @param {{ [key: string]: unknown }} 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. @@ -26,6 +27,7 @@ export class I18n { * The most used function - takes the key for a given piece of UI text and * returns the appropriate string. * + * @internal * @param {string} lookupKey - The lookup key of the string to use. * @param {{ [key: string]: unknown }} [options] - Any options passed with the translation string, e.g: for string interpolation. * @returns {string} The appropriate translation string. @@ -76,6 +78,7 @@ export class I18n { * Takes a translation string with placeholders, and replaces the placeholders * with the provided data * + * @internal * @param {string} translationString - The translation string * @param {{ [key: string]: unknown }} options - Any options passed with the translation string, e.g: for string interpolation. * @returns {string} The translation string to output, with $\{\} placeholders replaced @@ -94,6 +97,7 @@ export class I18n { /** * Replace translation string placeholders * + * @internal * @param {string} placeholderWithBraces - Placeholder with braces * @param {string} placeholderKey - Placeholder key * @returns {string} Placeholder value @@ -137,6 +141,7 @@ export class I18n { * - The implementation of Intl supports PluralRules (NOT true in IE11) * - The browser/OS has plural rules for the current locale (browser dependent) * + * @internal * @returns {boolean} Returns true if all conditions are met. Returns false otherwise. */ hasIntlPluralRulesSupport() { @@ -155,6 +160,7 @@ export class I18n { * - The implementation of Intl supports NumberFormat (also true in IE11) * - The browser/OS has number formatting rules for the current locale (browser dependent) * + * @internal * @returns {boolean} Returns true if all conditions are met. Returns false otherwise. */ hasIntlNumberFormatSupport() { @@ -175,6 +181,7 @@ export class I18n { * hasn't, it'll fall back to the 'other' plural form (unless that doesn't exist * either, in which case an error will be thrown) * + * @internal * @param {string} lookupKey - The lookup key of the string to use. * @param {number} count - Number used to determine which pluralisation to use. * @returns {PluralRule} The suffix associated with the correct pluralisation for this locale. @@ -228,6 +235,7 @@ export class I18n { * This is split out into a separate function to make it easier to test the * fallback behaviour in an environment where Intl.PluralRules exists. * + * @internal * @param {number} count - Number used to determine which pluralisation to use. * @returns {PluralRule} The pluralisation form for count in this locale. */ @@ -253,6 +261,7 @@ export class I18n { * 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. * + * @internal * @returns {string | undefined} The name of the pluralisation rule to use (a key for one * of the functions in this.pluralRules) */ @@ -306,6 +315,7 @@ export class I18n { * Spanish: European Portuguese (pt-PT), Italian (it), Spanish (es) * Welsh: Welsh (cy) * + * @internal * @type {{ [key: string]: string[] }} */ static pluralRulesMap = { @@ -356,6 +366,7 @@ export class I18n { * * The count must be a positive integer. Negative numbers and decimals aren't accounted for * + * @internal * @type {{ [key: string]: (count: number) => PluralRule }} */ static pluralRules = { @@ -468,6 +479,7 @@ export class I18n { /** * Plural rule category mnemonic tags * + * @internal * @typedef {'zero' | 'one' | 'two' | 'few' | 'many' | 'other'} PluralRule */ @@ -477,6 +489,7 @@ export class I18n { * Allows to group pluralised messages under a single key when passing * translations to a component's constructor * + * @internal * @typedef {object} TranslationPluralForms * @property {string} [other] - General plural form * @property {string} [zero] - Plural form used with 0 From 7a56bcee2bc70e62eb5f41ef0aecabd667ff6972 Mon Sep 17 00:00:00 2001 From: Colin Rotherham Date: Tue, 8 Aug 2023 15:34:11 +0100 Subject: [PATCH 3/4] Use JSDoc tag `@internal` for common helpers --- .../src/govuk/common/closest-attribute-value.mjs | 2 +- packages/govuk-frontend/src/govuk/common/index.mjs | 6 ++++-- .../govuk-frontend/src/govuk/common/normalise-dataset.mjs | 4 ++-- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/packages/govuk-frontend/src/govuk/common/closest-attribute-value.mjs b/packages/govuk-frontend/src/govuk/common/closest-attribute-value.mjs index 77e6a82050..b4bcd0f667 100644 --- a/packages/govuk-frontend/src/govuk/common/closest-attribute-value.mjs +++ b/packages/govuk-frontend/src/govuk/common/closest-attribute-value.mjs @@ -1,7 +1,7 @@ /** * Returns the value of the given attribute closest to the given element (including itself) * - * @private + * @internal * @param {Element} $element - The element to start walking the DOM tree up * @param {string} attributeName - The name of the attribute * @returns {string | null} Attribute value diff --git a/packages/govuk-frontend/src/govuk/common/index.mjs b/packages/govuk-frontend/src/govuk/common/index.mjs index 22d26b8945..4a66066439 100644 --- a/packages/govuk-frontend/src/govuk/common/index.mjs +++ b/packages/govuk-frontend/src/govuk/common/index.mjs @@ -15,7 +15,7 @@ * (e.g. \{'i18n.showSection': 'Show section'\}) and combines them together, with * greatest priority on the LAST item passed in. * - * @private + * @internal * @returns {{ [key: string]: unknown }} A flattened object of key-value pairs. */ export function mergeConfigs(/* configObject1, configObject2, ...configObjects */) { @@ -25,6 +25,7 @@ export function mergeConfigs(/* configObject1, configObject2, ...configObjects * * each of our objects, nor transform our dataset from a flat list into a * nested object. * + * @internal * @param {{ [key: string]: unknown }} configObject - Deeply nested object * @returns {{ [key: string]: unknown }} Flattened object with dot-separated keys */ @@ -38,6 +39,7 @@ export function mergeConfigs(/* configObject1, configObject2, ...configObjects * * depth in the object. At each level we prepend the previous level names to * the key using `prefix`. * + * @internal * @param {Partial<{ [key: string]: unknown }>} obj - Object to flatten * @param {string} [prefix] - Optional dot-separated prefix */ @@ -90,7 +92,7 @@ export function mergeConfigs(/* configObject1, configObject2, ...configObjects * * Extracts keys starting with a particular namespace from a flattened config * object, removing the namespace in the process. * - * @private + * @internal * @param {{ [key: string]: unknown }} configObject - The object to extract key-value pairs from. * @param {string} namespace - The namespace to filter keys with. * @returns {{ [key: string]: unknown }} Flattened object with dot-separated key namespace removed diff --git a/packages/govuk-frontend/src/govuk/common/normalise-dataset.mjs b/packages/govuk-frontend/src/govuk/common/normalise-dataset.mjs index 28ec462bee..51e1521684 100644 --- a/packages/govuk-frontend/src/govuk/common/normalise-dataset.mjs +++ b/packages/govuk-frontend/src/govuk/common/normalise-dataset.mjs @@ -9,7 +9,7 @@ * Designed to be used to convert config passed via data attributes (which are * always strings) into something sensible. * - * @private + * @internal * @param {string} value - The value to normalise * @returns {string | boolean | number | undefined} Normalised data */ @@ -42,7 +42,7 @@ export function normaliseString(value) { * * Loop over an object and normalise each value using normaliseData function * - * @private + * @internal * @param {DOMStringMap} dataset - HTML element dataset * @returns {{ [key: string]: unknown }} Normalised dataset */ From fdf80575ded1810fc11a34528b75906a24c4bdb4 Mon Sep 17 00:00:00 2001 From: Colin Rotherham Date: Tue, 8 Aug 2023 15:34:40 +0100 Subject: [PATCH 4/4] Remove unused JSDoc tag `@module` --- packages/govuk-frontend/src/govuk/common/index.mjs | 2 -- 1 file changed, 2 deletions(-) diff --git a/packages/govuk-frontend/src/govuk/common/index.mjs b/packages/govuk-frontend/src/govuk/common/index.mjs index 4a66066439..e8e66563ac 100644 --- a/packages/govuk-frontend/src/govuk/common/index.mjs +++ b/packages/govuk-frontend/src/govuk/common/index.mjs @@ -4,8 +4,6 @@ * IMPORTANT: If a helper require a polyfill, please isolate it in its own module * so that the polyfill can be properly tree-shaken and does not burden * the components that do not need that helper - * - * @module common/index */ /**