From b7d0b85a158ada888fe57338c1d25a09a820ccca Mon Sep 17 00:00:00 2001
From: teidesu <86301490+teidesu@users.noreply.github.com>
Date: Mon, 12 Sep 2022 15:01:43 +0300
Subject: [PATCH] docs(i18n): improved docs

---
 packages/i18n/README.md              |  2 +-
 packages/i18n/src/plurals/english.ts | 16 ++++++++++++++++
 packages/i18n/src/plurals/russian.ts | 15 +++++++++++++++
 packages/i18n/src/types.ts           | 22 ++++++++++++++++++++++
 packages/i18n/src/utils.ts           | 11 +++++++++++
 5 files changed, 65 insertions(+), 1 deletion(-)

diff --git a/packages/i18n/README.md b/packages/i18n/README.md
index cb5dcdaf..e365b62c 100644
--- a/packages/i18n/README.md
+++ b/packages/i18n/README.md
@@ -2,4 +2,4 @@
 
 This package implements utility for i18n functionality in `@mtcute/client` based apps.
 
-Documentation is TBA.
+Learn more in the [Guide](/guide/topics/i18n).
diff --git a/packages/i18n/src/plurals/english.ts b/packages/i18n/src/plurals/english.ts
index 897b825a..5bd338ad 100644
--- a/packages/i18n/src/plurals/english.ts
+++ b/packages/i18n/src/plurals/english.ts
@@ -1,5 +1,8 @@
 import { I18nValue, I18nValueDynamic } from "../types";
 
+/**
+ * Get an English ordinal suffix (st/nd/rd/th) for a given number.
+ */
 export function ordinalSuffixEnglish(n: number): string {
     const v = n % 100
     if (v > 3 && v < 21) return 'th'
@@ -15,10 +18,23 @@ export function ordinalSuffixEnglish(n: number): string {
     }
 }
 
+/**
+ * Pluralize a value by English rules
+ *
+ * @param n  Number of items
+ * @param one  Value for "one" (1 item)
+ * @param many  Value for "many" (0 items, 2 items, many items)
+ */
 export function pluralizeEnglish<T>(n: number, one: T, many: T): T {
     return n === 1 ? one : many
 }
 
+/**
+ * Create a complex English pluralized value
+ *
+ * @param one  Value for "one" (1 item)
+ * @param many  Value for "many" (0 items, 2 items, many items)
+ */
 export function createPluralEnglish<Args extends any[] = []>(
     one: I18nValue<[number, ...Args]>,
     many: I18nValue<[number, ...Args]>
diff --git a/packages/i18n/src/plurals/russian.ts b/packages/i18n/src/plurals/russian.ts
index d560f27d..59e38a08 100644
--- a/packages/i18n/src/plurals/russian.ts
+++ b/packages/i18n/src/plurals/russian.ts
@@ -1,5 +1,13 @@
 import { I18nValue, I18nValueDynamic } from '../types'
 
+/**
+ * Pluralize a value by Russian rules
+ *
+ * @param n  Number of items
+ * @param one  Value for "one" (1 стол, 21 стол)
+ * @param few  Value for "few" (2 стола, 42 стола)
+ * @param many  Value for "many" (5 столов, 100 столов, 0 столов, нет столов)
+ */
 export function pluralizeRussian<T>(
     n: number,
     one: T,
@@ -20,6 +28,13 @@ export function pluralizeRussian<T>(
     return many
 }
 
+/**
+ * Create a complex Russian pluralized value
+ *
+ * @param one  Value for "one" (1 стол, 21 стол)
+ * @param few  Value for "few" (2 стола, 42 стола)
+ * @param many  Value for "many" (5 столов, 100 столов, 0 столов, нет столов)
+ */
 export function createPluralRussian<Args extends any[] = []>(
     one: I18nValue<[number, ...Args]>,
     few: I18nValue<[number, ...Args]>,
diff --git a/packages/i18n/src/types.ts b/packages/i18n/src/types.ts
index 135d38f5..d1f6c342 100644
--- a/packages/i18n/src/types.ts
+++ b/packages/i18n/src/types.ts
@@ -3,11 +3,21 @@ import type { FormattedString } from '@mtcute/client'
 type Values<T> = T[keyof T]
 type SafeGet<T, K extends string> = T extends Record<K, any> ? T[K] : never
 
+/**
+ * Literal translated value, represented by (optionally formatted) string
+ */
 export type I18nValueLiteral = string | FormattedString<any>
+/**
+ * Dynamic translated value, represented by a
+ * function resolving to a literal one
+ */
 export type I18nValueDynamic<Args extends any[] = any[]> = (
     ...args: Args
 ) => I18nValueLiteral
 
+/**
+ * Translated value. Can either be actual value or a function resolving to one
+ */
 export type I18nValue<Args extends any[] = any[]> =
     | I18nValueLiteral
     | I18nValueDynamic<Args>
@@ -29,8 +39,16 @@ type ExtractParameter<Strings, K extends string> = GetValueNested<
     ? R
     : []
 
+/**
+ * Translation "adapter".
+ *
+ * Used to extract language from `Input` object.
+ */
 export type MtcuteI18nAdapter<Input> = (obj: Input) => string | null | undefined
 
+/**
+ * Translation function.
+ */
 export type MtcuteI18nFunction<Strings, Input> = <
     K extends NestedKeysDelimited<Strings>
 >(
@@ -39,6 +57,10 @@ export type MtcuteI18nFunction<Strings, Input> = <
     ...params: ExtractParameter<Strings, K>
 ) => string | FormattedString<any>
 
+/**
+ * Wrapper type for i18n object containing strings for a language
+ * other than the primary one. Used to provide type safety.
+ */
 export type OtherLanguageWrap<Strings> = {
     [key in keyof Strings]?: Strings[key] extends I18nValue
         ? I18nValue
diff --git a/packages/i18n/src/utils.ts b/packages/i18n/src/utils.ts
index bae37675..6b606a67 100644
--- a/packages/i18n/src/utils.ts
+++ b/packages/i18n/src/utils.ts
@@ -6,6 +6,11 @@ try {
     client = require('@mtcute/client')
 } catch (e) {}
 
+/**
+ * Create an index of i18n strings delimited by "."
+ *
+ * @param strings  Strings object
+ */
 export function createI18nStringsIndex(
     strings: Record<string, any>
 ): Record<string, I18nValue> {
@@ -28,6 +33,12 @@ export function createI18nStringsIndex(
     return ret
 }
 
+/**
+ * Extract language from `@mtcute/client` update. Can be used for customized
+ * adapters or external i18n libraries.
+ *
+ * @param update  Update to extract language from
+ */
 export function extractLanguageFromUpdate(
     update: ParsedUpdate['data']
 ): string | null | undefined {