docs: Update API docs

Author: eemeli

fluent-bundle/src/builtins.ts

@@ -50,8 +50,8 @@ const NUMBER_ALLOWED = [
  *
  *     pi = The value of π is {NUMBER($pi, maximumFractionDigits: 2)}.
  *
- * The implementation expects an array of `FluentValues` representing the
- * positional arguments, and an object of named `FluentValues` representing the
+ * The implementation expects an array of {@link FluentValue | FluentValues} representing the
+ * positional arguments, and an object of named {@link FluentValue | FluentValues} representing the
  * named parameters.
  *
  * The following options are recognized:
@@ -121,8 +121,8 @@ const DATETIME_ALLOWED = [
  *
  *     now = It's {DATETIME($today, month: "long")}.
  *
- * The implementation expects an array of `FluentValues` representing the
- * positional arguments, and an object of named `FluentValues` representing the
+ * The implementation expects an array of {@link FluentValue | FluentValues} representing the
+ * positional arguments, and an object of named {@link FluentValue | FluentValues} representing the
  * named parameters.
  *
  * The following options are recognized:

fluent-bundle/src/index.ts

@@ -1,10 +1,8 @@
 /**
- * @module fluent
- * @overview
- *
- * `fluent` is a JavaScript implementation of Project Fluent, a localization
+ * A JavaScript implementation of Project Fluent, a localization
  * framework designed to unleash the expressive power of the natural language.
  *
+ * @module
  */
 
 export type { Message } from "./ast.js";

fluent-bundle/src/resolver.ts

@@ -1,8 +1,4 @@
-/* global Intl */
-
 /**
- * @overview
- *
  * The role of the Fluent resolver is to format a `Pattern` to an instance of
  * `FluentValue`. For performance reasons, primitive strings are considered
  * such instances, too.

fluent-bundle/src/types.ts

@@ -63,7 +63,7 @@ export abstract class FluentType<T> {
 }
 
 /**
- * A `FluentType` representing no correct value.
+ * A {@link FluentType} representing no correct value.
  */
 export class FluentNone extends FluentType<string> {
   /**
@@ -83,7 +83,7 @@ export class FluentNone extends FluentType<string> {
 }
 
 /**
- * A `FluentType` representing a number.
+ * A {@link FluentType} representing a number.
  *
  * A `FluentNumber` instance stores the number value of the number it
  * represents. It may also store an option bag of options which will be passed
@@ -120,7 +120,7 @@ export class FluentNumber extends FluentType<number> {
 }
 
 /**
- * A `FluentType` representing a date and time.
+ * A {@link FluentType} representing a date and time.
  *
  * A `FluentDateTime` instance stores a Date object, Temporal object, or a number
  * as a numerical timestamp in milliseconds. It may also store an

fluent-langneg/src/index.ts

@@ -1,15 +1,10 @@
-/*
- * @module fluent-langneg
- * @overview
- *
- * `fluent-langneg` provides language negotiation API that fits into
+/**
+ * A language negotiation API that fits into the
  * Project Fluent localization composition and fallbacking strategy.
  *
+ * @module
  */
 
-export {
-  negotiateLanguages,
-  NegotiateLanguagesOptions,
-} from "./negotiate_languages.js";
+export { negotiateLanguages } from "./negotiate_languages.js";
 export { acceptedLanguages } from "./accepted_languages.js";
 export { filterMatches } from "./matches.js";

fluent-langneg/src/locale.ts

@@ -1,5 +1,3 @@
-/* eslint no-magic-numbers: 0 */
-
 const languageCodeRe = "([a-z]{2,3}|\\*)";
 const scriptCodeRe = "(?:-([a-z]{4}|\\*))";
 const regionCodeRe = "(?:-([a-z]{2}|\\*))";

fluent-langneg/src/matches.ts

@@ -1,5 +1,3 @@
-/* eslint no-magic-numbers: 0 */
-
 import { Locale } from "./locale.js";
 
 /**
@@ -9,68 +7,68 @@ import { Locale } from "./locale.js";
  * The algorithm is based on the BCP4647 3.3.2 Extended Filtering algorithm,
  * with several modifications:
  *
- *  1) available locales are treated as ranges
+ * ### 1. Available locales are treated as ranges
  *
- *    This change allows us to match a more specific request against
- *    more generic available locale.
+ * This change allows us to match a more specific request against
+ * more generic available locale.
  *
- *    For example, if the available locale list provides locale `en`,
- *    and the requested locale is `en-US`, we treat the available locale as
- *    a locale that matches all possible english requests.
+ * For example, if the available locale list provides locale `en`,
+ * and the requested locale is `en-US`, we treat the available locale as
+ * a locale that matches all possible english requests.
  *
- *    This means that we expect available locale ID to be as precize as
- *    the matches they want to cover.
+ * This means that we expect available locale ID to be as precize as
+ * the matches they want to cover.
  *
- *    For example, if there is only `sr` available, it's ok to list
- *    it in available locales. But once the available locales has both,
- *    Cyrl and Latn variants, the locale IDs should be `sr-Cyrl` and `sr-Latn`
- *    to avoid any `sr-*` request to match against whole `sr` range.
+ * For example, if there is only `sr` available, it's ok to list
+ * it in available locales. But once the available locales has both,
+ * Cyrl and Latn variants, the locale IDs should be `sr-Cyrl` and `sr-Latn`
+ * to avoid any `sr-*` request to match against whole `sr` range.
  *
- *    What it does ([requested] * [available] = [supported]):
+ * What it does ([requested] * [available] = [supported]):
  *
- *    ['en-US'] * ['en'] = ['en']
+ *     ['en-US'] * ['en'] = ['en']
  *
- *  2) likely subtags from LDML 4.3 Likely Subtags has been added
+ * ### 2. Likely subtags from LDML 4.3 Likely Subtags has been added
  *
- *    The most obvious likely subtag that can be computed is a duplication
- *    of the language field onto region field (`fr` => `fr-FR`).
+ * The most obvious likely subtag that can be computed is a duplication
+ * of the language field onto region field (`fr` => `fr-FR`).
  *
- *    On top of that, likely subtags may use a list of mappings, that
- *    allow the algorithm to handle non-obvious matches.
- *    For example, making sure that we match `en` to `en-US` or `sr` to
- *    `sr-Cyrl`, while `sr-RU` to `sr-Latn-RU`.
+ * On top of that, likely subtags may use a list of mappings, that
+ * allow the algorithm to handle non-obvious matches.
+ * For example, making sure that we match `en` to `en-US` or `sr` to
+ * `sr-Cyrl`, while `sr-RU` to `sr-Latn-RU`.
  *
- *    This list can be taken directly from CLDR Supplemental Data.
+ * This list can be taken directly from CLDR Supplemental Data.
  *
- *    What it does ([requested] * [available] = [supported]):
+ * What it does ([requested] * [available] = [supported]):
  *
- *    ['fr'] * ['fr-FR'] = ['fr-FR']
- *    ['en'] * ['en-US'] = ['en-US']
- *    ['sr'] * ['sr-Latn', 'sr-Cyrl'] = ['sr-Cyrl']
+ *     ['fr'] * ['fr-FR'] = ['fr-FR']
+ *     ['en'] * ['en-US'] = ['en-US']
+ *     ['sr'] * ['sr-Latn', 'sr-Cyrl'] = ['sr-Cyrl']
  *
- *  3) variant/region range check has been added
+ * ### 3. Variant/region range check has been added
  *
- *    Lastly, the last form of check is against the requested locale ID
- *    but with the variant/region field replaced with a `*` range.
+ * Lastly, the last form of check is against the requested locale ID
+ * but with the variant/region field replaced with a `*` range.
  *
- *    The rationale here laid out in LDML 4.4 Language Matching:
- *      "(...) normally the fall-off between the user's languages is
- *      substantially greated than regional variants."
+ * The rationale here laid out in LDML 4.4 Language Matching:
+ *   "(...) normally the fall-off between the user's languages is
+ *   substantially greated than regional variants."
  *
- *    In other words, if we can't match for the given region, maybe
- *    we can match for the same language/script but other region, and
- *    it will in most cases be preferred over falling back on the next
- *    language.
+ * In other words, if we can't match for the given region, maybe
+ * we can match for the same language/script but other region, and
+ * it will in most cases be preferred over falling back on the next
+ * language.
  *
- *    What it does ([requested] * [available] = [supported]):
+ * What it does ([requested] * [available] = [supported]):
  *
- *    ['en-AU'] * ['en-US'] = ['en-US']
- *    ['sr-RU'] * ['sr-Latn-RO'] = ['sr-Latn-RO'] // sr-RU -> sr-Latn-RU
+ *     ['en-AU'] * ['en-US'] = ['en-US']
+ *     ['sr-RU'] * ['sr-Latn-RO'] = ['sr-Latn-RO'] // sr-RU -> sr-Latn-RU
  *
- *    It works similarly to getParentLocales algo, except that we stop
- *    after matching against variant/region ranges and don't try to match
- *    ignoring script ranges. That means that `sr-Cyrl` will never match
- *    against `sr-Latn`.
+ * It works similarly to getParentLocales algo, except that we stop
+ * after matching against variant/region ranges and don't try to match
+ * ignoring script ranges. That means that `sr-Cyrl` will never match
+ * against `sr-Latn`.
  */
 export function filterMatches(
   requestedLocales: Array<string>,

fluent-langneg/src/negotiate_languages.ts

@@ -1,58 +1,57 @@
 import { filterMatches } from "./matches.js";
 
-export interface NegotiateLanguagesOptions {
-  strategy?: "filtering" | "matching" | "lookup";
-  defaultLocale?: string;
-}
-
 /**
  * Negotiates the languages between the list of requested locales against
  * a list of available locales.
  *
  * It accepts three arguments:
  *
- *   requestedLocales:
- *     an Array of strings with BCP47 locale IDs sorted
- *     according to user preferences.
+ * - `requestedLocales`:
+ *   an Array of strings with BCP47 locale IDs sorted
+ *   according to user preferences.
  *
- *   availableLocales:
- *     an Array of strings with BCP47 locale IDs of locale for which
- *     resources are available. Unsorted.
+ * - `availableLocales`:
+ *   an Array of strings with BCP47 locale IDs of locale for which
+ *   resources are available. Unsorted.
  *
- *   options:
- *     An object with the following, optional keys:
+ * - `options`:
+ *   An object with the following, optional keys:
  *
- *       strategy: 'filtering' (default) | 'matching' | 'lookup'
+ *   - `strategy`: `'filtering'` (default) | `'matching'` | `'lookup'`
  *
- *       defaultLocale:
- *         a string with BCP47 locale ID to be used
- *         as a last resort locale.
+ *   - `defaultLocale`:
+ *       a string with BCP47 locale ID to be used
+ *       as a last resort locale.
  *
  *
  * It returns an Array of strings with BCP47 locale IDs sorted according to the
  * user preferences.
  *
  * The exact list will be selected differently depending on the strategy:
  *
- *   'filtering': (default)
- *     In the filtering strategy, the algorithm will attempt to match
- *     as many keys in the available locales in order of the requested locales.
+ * - `'filtering'`: (default)<br>
+ *   In the filtering strategy, the algorithm will attempt to match
+ *   as many keys in the available locales in order of the requested locales.
  *
- *   'matching':
- *     In the matching strategy, the algorithm will attempt to find the
- *     best possible match for each element of the requestedLocales list.
+ * - `'matching'`:<br>
+ *   In the matching strategy, the algorithm will attempt to find the
+ *   best possible match for each element of the requestedLocales list.
  *
- *   'lookup':
- *     In the lookup strategy, the algorithm will attempt to find a single
- *     best available locale based on the requested locales list.
+ * - `'lookup'`:<br>
+ *   In the lookup strategy, the algorithm will attempt to find a single
+ *   best available locale based on the requested locales list.
  *
- *     This strategy requires defaultLocale option to be set.
+ *   This strategy requires defaultLocale option to be set.
  */
 export function negotiateLanguages(
   requestedLocales: Readonly<Array<string>>,
   availableLocales: Readonly<Array<string>>,
-  { strategy = "filtering", defaultLocale }: NegotiateLanguagesOptions = {}
+  options?: {
+    strategy?: "filtering" | "matching" | "lookup";
+    defaultLocale?: string;
+  }
 ): Array<string> {
+  const { strategy = "filtering", defaultLocale } = options ?? {};
   const supportedLocales = filterMatches(
     Array.from(requestedLocales ?? []).map(String),
     Array.from(availableLocales ?? []).map(String),

fluent-react/src/index.ts

@@ -1,13 +1,9 @@
 /**
- * @module fluent-react
- * @overview
+ * React bindings for Fluent.
+ * Takes advantage of React's Components system and the virtual DOM.
+ * Translations are exposed to components via the provider pattern.
  *
-
- * `fluent-react` provides React bindings for Fluent.  It takes advantage of
- * React's Components system and the virtual DOM.  Translations are exposed to
- * components via the provider pattern.
- *
- * Consult the documentation of the `LocalizationProvider` and the `Localized`
+ * Consult the documentation of the {@link LocalizationProvider} and the {@link Localized}
  * components for more information.
  *
  * @example
@@ -18,6 +14,8 @@
  *     </Localized>
  * </LocalizationProvider>
  * ```
+ *
+ * @module
  */
 
 export { ReactLocalization } from "./localization.js";

fluent-react/src/localization.ts

@@ -25,12 +25,12 @@ const defaultReportError = (error: Error): void => {
  * `ReactLocalization` handles translation formatting and fallback.
  *
  * The current negotiated fallback chain of languages is stored in the
- * `ReactLocalization` instance in form of an iterable of `FluentBundle`
+ * `ReactLocalization` instance in form of an iterable of {@link FluentBundle}
  * instances. This iterable is used to find the best existing translation for
  * a given identifier.
  *
- * The `ReactLocalization` class instances are exposed to `Localized` elements
- * via the `LocalizationProvider` component.
+ * The `ReactLocalization` class instances are exposed to {@link Localized} elements
+ * via the {@link LocalizationProvider} component.
  */
 export class ReactLocalization {
   public bundles: Iterable<FluentBundle>;