docs: add i18n documentation

Author: Adam Butterworth

.eslintignore

@@ -1,5 +1,6 @@
 .idea
 coverage
 dist
+docs
 node_modules
 src/analytics/segment.js

jsdoc.json

@@ -22,7 +22,6 @@
       "destination": "./docs/api",
       "encoding": "utf8",
       "private": true,
-      "recurse": true,
-      "template": "./node_modules/minami"
+      "recurse": true
   }
 }

package-lock.json

@@ -42,7 +42,6 @@
     "enzyme-adapter-react-16": "1.15.1",
     "husky": "3.0.9",
     "jsdoc": "3.6.3",
-    "minami": "1.2.3",
     "prop-types": "15.7.2",
     "react": "16.11.0",
     "react-dom": "16.11.0",

package.json

@@ -216,7 +216,6 @@ export async function hydrateAuthenticatedUser() {
  * ```
  *
  * @name HttpClient
- * @
  * @property {function} get
  * @property {function} head
  * @property {function} options

src/auth/index.js

@@ -28,14 +28,14 @@ COUNTRIES.registerLocale(require('i18n-iso-countries/langs/uk.json'));
 /**
  * Provides a lookup table of country IDs to country names for the current locale.
  *
- * @memberof I18n
+ * @memberof module:I18n
  */
-export const getCountryMessages = (locale) => {
+export function getCountryMessages(locale) {
   const primaryLanguageSubtag = getPrimaryLanguageSubtag(locale);
   const languageCode = countryLangs().includes(primaryLanguageSubtag) ? primaryLanguageSubtag : 'en';
 
   return COUNTRIES.getNames(languageCode);
-};
+}
 
 /**
  * Provides a list of countries represented as objects of the following shape:
@@ -48,9 +48,9 @@ export const getCountryMessages = (locale) => {
  * TODO: ARCH-878: The list should be sorted alphabetically in the current locale.
  * This is useful for populating dropdowns.
  *
- * @memberof I18n
+ * @memberof module:I18n
  */
-export const getCountryList = (locale) => {
+export function getCountryList(locale) {
   const countryMessages = getCountryMessages(locale);
   return Object.entries(countryMessages).map(([code, name]) => ({ code, name }));
-};
+}

src/i18n/countries.js

@@ -2,8 +2,68 @@
  * The i18n module relies on react-intl and re-exports all of that package's exports.
  *
  * @module I18n
+ * @see {@link https://github.com/formatjs/react-intl/blob/master/docs/Components.md|React Intl} for components exported from this module.
  *
- *
+ */
+
+/**
+ * @name FormattedDate
+ * @kind class
+ * @see {@link https://github.com/formatjs/react-intl/blob/master/docs/Components.md#formatteddate|React Intl}
+ */
+
+/**
+ * @name FormattedTime
+ * @kind class
+ * @see {@link https://github.com/formatjs/react-intl/blob/master/docs/Components.md#formatteddate|React Intl}
+ */
+
+/**
+ * @name FormattedRelative
+ * @kind class
+ * @see {@link https://github.com/formatjs/react-intl/blob/master/docs/Components.md#formattedrelative|React Intl}
+ */
+
+/**
+ * @name FormattedNumber
+ * @kind class
+ * @see {@link https://github.com/formatjs/react-intl/blob/master/docs/Components.md#formattednumber|React Intl}
+ */
+
+/**
+ * @name FormattedPlural
+ * @kind class
+ * @see {@link https://github.com/formatjs/react-intl/blob/master/docs/Components.md#formattedplural|React Intl}
+ */
+
+/**
+ * @name FormattedMessage
+ * @kind class
+ * @see {@link https://github.com/formatjs/react-intl/blob/master/docs/Components.md#formattedmessage|React Intl}
+ */
+
+/**
+ * @name FormattedMessage
+ * @kind class
+ * @see {@link https://github.com/formatjs/react-intl/blob/master/docs/Components.md#formattedmessage|React Intl}
+ */
+
+/**
+ * @name IntlProvider
+ * @kind class
+ * @see {@link https://github.com/formatjs/react-intl/blob/master/docs/Components.md#intlprovider|React Intl}
+ */
+
+/**
+ * @name intlShape
+ * @kind constant
+ * @see {@link https://github.com/formatjs/react-intl/blob/master/docs/API.md#intlshape|React Intl}
+ */
+
+/**
+ * @name defineMessages
+ * @kind function
+ * @see {@link https://github.com/formatjs/react-intl/blob/master/docs/API.md#definemessages|React Intl}
  */
 
 export {

src/i18n/index.js

@@ -1,11 +1,3 @@
-/**
- * The i18n module relies on react-intl and re-exports all of that package's exports.
- *
- * @module I18n
- *
- *
- */
-
 import PropTypes from 'prop-types';
 import { addLocaleData } from 'react-intl';
 import arLocale from 'react-intl/locale-data/ar';
@@ -72,6 +64,7 @@ let messages = null;
 
 /**
  *
+ * @ignore
  * @returns {LoggingService}
  *
  */
@@ -83,13 +76,13 @@ export const getLoggingService = () => loggingService;
 export const LOCALE_TOPIC = 'LOCALE';
 
 /**
- * @memberof I18n
+ * @memberof module:I18n
  */
 export const LOCALE_CHANGED = `${LOCALE_TOPIC}.CHANGED`;
 
 /**
  *
- * @memberof I18n
+ * @memberof module:I18n
  * @returns {Cookies}
  */
 export function getCookies() {
@@ -119,9 +112,11 @@ addLocaleData([
  * may be 2 or more characters.
  *
  * @param {string} code
- * @memberof I18n
+ * @memberof module:I18n
  */
-export const getPrimaryLanguageSubtag = code => code.split('-')[0];
+export function getPrimaryLanguageSubtag(code) {
+  return code.split('-')[0];
+}
 
 /**
  * Finds the closest supported locale to the one provided.  This is done in three steps:
@@ -133,9 +128,9 @@ export const getPrimaryLanguageSubtag = code => code.split('-')[0];
  *
  * @param {string} locale
  * @returns {string}
- * @memberof I18n
+ * @memberof module:I18n
  */
-export const findSupportedLocale = (locale) => {
+export function findSupportedLocale(locale) {
   if (messages[locale] !== undefined) {
     return locale;
   }
@@ -145,7 +140,7 @@ export const findSupportedLocale = (locale) => {
   }
 
   return 'en';
-};
+}
 
 /**
  * Get the locale from the cookie or, failing that, the browser setting.
@@ -155,9 +150,9 @@ export const findSupportedLocale = (locale) => {
  * @param {string} locale If a locale is provided, returns the closest supported locale. Optional.
  * @throws An error if i18n has not yet been configured.
  * @returns {string}
- * @memberof I18n
+ * @memberof module:I18n
  */
-export const getLocale = (locale) => {
+export function getLocale(locale) {
   if (messages === null) {
     throw new Error('getLocale called before configuring i18n. Call configure with messages first.');
   }
@@ -176,38 +171,42 @@ export const getLocale = (locale) => {
   // Thus the toLowerCase, for consistency.
   // https://developer.mozilla.org/en-US/docs/Web/API/NavigatorLanguage/language
   return findSupportedLocale(global.navigator.language.toLowerCase());
-};
+}
 
 /**
  * Returns messages for the provided locale, or the user's preferred locale if no argument is
  * provided.
  *
  * @param {string} [locale=getLocale()]
- * @memberof I18n
+ * @memberof module:I18n
  */
-export const getMessages = (locale = getLocale()) => messages[locale];
+export function getMessages(locale = getLocale()) {
+  return messages[locale];
+}
 
 /**
  * Determines if the provided locale is a right-to-left language.
  *
  * @param {string} locale
- * @memberof I18n
+ * @memberof module:I18n
  */
-export const isRtl = locale => rtlLocales.includes(locale);
+export function isRtl(locale) {
+  return rtlLocales.includes(locale);
+}
 
 /**
  * Handles applying the RTL stylesheet and "dir=rtl" attribute to the html tag if the current locale
  * is a RTL language.
  *
- * @memberof I18n
+ * @memberof module:I18n
  */
-export const handleRtl = () => {
+export function handleRtl() {
   if (isRtl(getLocale())) {
     global.document.getElementsByTagName('html')[0].setAttribute('dir', 'rtl');
   } else {
     global.document.getElementsByTagName('html')[0].setAttribute('dir', 'ltr');
   }
-};
+}
 
 const messagesShape = {
   ar: PropTypes.objectOf(PropTypes.string), // Arabic
@@ -242,7 +241,7 @@ const optionsShape = {
  *
  * @param {Array} [messagesArray=[]]
  * @returns {Object}
- * @memberof I18n
+ * @memberof module:I18n
  */
 export function mergeMessages(messagesArray = []) {
   return Array.isArray(messagesArray) ? merge({}, ...messagesArray) : {};
@@ -258,9 +257,9 @@ export function mergeMessages(messagesArray = []) {
  * @param {LoggingService} options.loggingService
  * @param {Object} options.config
  * @param {Object} options.messages
- * @memberof I18n
+ * @memberof module:I18n
  */
-export const configure = (options) => {
+export function configure(options) {
   PropTypes.checkPropTypes(optionsShape, options, 'property', 'i18n');
   // eslint-disable-next-line prefer-destructuring
   loggingService = options.loggingService;
@@ -283,4 +282,4 @@ export const configure = (options) => {
   }
 
   handleRtl();
-};
+}