Docs: improve internal documentation

Author: robisim74

src/services/collator.ts

@@ -100,10 +100,23 @@ export interface ICollator {
 
 }
 
+/**
+ * Intl.Collator APIs.
+ */
 @Injectable() export class Collator implements ICollator {
 
     constructor(private locale: LocaleService, private translation: TranslationService) { }
 
+    /**
+     * Compares two keys by the value of translation according to the current language.
+     * @param key1, key2 The keys of the values to compare
+     * @param extension Unicode extension key, e.g. 'co-phonebk'
+     * @param options Default is { usage: 'sort', sensitivity: 'variant' }
+     * @return A negative value if the value of translation of key1 comes before the value of translation of key2;
+     *         a positive value if key1 comes after key2;
+     *         0 if they are considered equal or Intl.Collator is not supported
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Collator
+     */
     public compare(
         key1: string,
         key2: string,
@@ -124,6 +137,16 @@ export interface ICollator {
         return new Intl.Collator(locale, options).compare(value1, value2);
     }
 
+    /**
+     * Sorts an array of objects or an array of arrays according to the current language.
+     * @param list The array to be sorted
+     * @param keyName The column that contains the keys of the values to be ordered
+     * @param order 'asc' or 'desc'. The default value is 'asc'
+     * @param extension Unicode extension key, e.g. 'co-phonebk'
+     * @param options Default is { usage: 'sort', sensitivity: 'variant' }
+     * @return The same sorted list or the same list if Intl.Collator is not supported
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Collator
+     */
     public sort(
         list: any[],
         keyName: any,
@@ -145,6 +168,16 @@ export interface ICollator {
         return list;
     }
 
+    /**
+     * Sorts asynchronously an array of objects or an array of arrays according to the current language.
+     * @param list The array to be sorted
+     * @param keyName The column that contains the keys of the values to be ordered
+     * @param order 'asc' or 'desc'. The default value is 'asc'
+     * @param extension Unicode extension key, e.g. 'co-phonebk'
+     * @param options Default is { usage: 'sort', sensitivity: 'variant' }
+     * @return An observable of the sorted list or of the same list if Intl.Collator is not supported
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Collator
+     */
     public sortAsync(
         list: any[],
         keyName: any,
@@ -158,6 +191,16 @@ export interface ICollator {
         });
     }
 
+    /**
+     * Matches a string into an array of objects or an array of arrays
+     * according to the current language.
+     * @param s The string to search
+     * @param list The array in which to search
+     * @param keyNames An array that contains the columns to look for
+     * @param options Default is { usage: 'search' }
+     * @return A filtered list or the same list if Intl.Collator is not supported
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Collator
+     */
     public search(
         s: string,
         list: any[],
@@ -184,6 +227,16 @@ export interface ICollator {
         return matches;
     }
 
+    /**
+     * Matches asynchronously a string into an array of objects or an array of arrays
+     * according to the current language.
+     * @param s The string to search
+     * @param list The array in which to search
+     * @param keyNames An array that contains the columns to look for
+     * @param options Default is { usage: 'search' }
+     * @return An observable of the filtered list or the same list if Intl.Collator is not supported
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Collator
+     */
     public searchAsync(
         s: string,
         list: any[],

src/services/l10n-loader.ts

@@ -16,6 +16,9 @@ import { TranslationService } from '../services/translation.service';
         private translation: TranslationService
     ) { }
 
+    /**
+     * Loads l10n services.
+     */
     public async load(): Promise<void> {
         // LocaleService initialization.
         if (Object.keys(this.localeConfig).length > 0) {

src/services/locale-storage.ts

@@ -4,20 +4,20 @@ import { LOCALE_CONFIG, LocaleConfig } from '../models/l10n-config';
 import { StorageStrategy } from '../models/types';
 
 /**
- * Implement this class-interface to create a custom storage for default locale & currency.
+ * Implement this class-interface to create a custom storage for default locale, currency & timezone.
  */
 @Injectable() export abstract class LocaleStorage {
 
     /**
      * This method must contain the logic to read the storage.
-     * @param name 'defaultLocale' or 'currency'
+     * @param name 'defaultLocale', 'currency' or 'timezone'
      * @return A promise with the value of the given name
      */
     public abstract async read(name: string): Promise<string | null>;
 
     /**
      * This method must contain the logic to write the storage.
-     * @param name 'defaultLocale' or 'currency'
+     * @param name 'defaultLocale', 'currency' or 'timezone'
      * @param value The value for the given name
      */
     public abstract async write(name: string, value: string): Promise<void>;

src/services/locale-validation.ts

@@ -15,10 +15,17 @@ export interface ILocaleValidation {
 
 }
 
+/**
+ * Provides the methods to convert strings according to default locale.
+ */
 @Injectable() export class LocaleValidation implements ILocaleValidation {
 
     constructor(private decimalCode: DecimalCode) { }
 
+    /**
+     * Converts a string to a number according to default locale.
+     * If the string cannot be converted to a number, returns NaN.
+     */
     public parseNumber(s: string): number | null {
         if (s == "") {
             return null;

src/services/locale.service.ts

@@ -69,6 +69,9 @@ export interface ILocaleService {
 
 }
 
+/**
+ * Manages language, default locale, currency & timezone.
+ */
 @Injectable() export class LocaleService implements ILocaleService {
 
     @Output() public languageCodeChanged: EventEmitter<string> = new EventEmitter<string>(true);

src/services/translation.service.ts

@@ -43,6 +43,9 @@ export interface ITranslationService {
 
 }
 
+/**
+ * Manages the translation data.
+ */
 @Injectable() export class TranslationService implements ITranslationService {
 
     public translationError: Subject<any> = new Subject();
@@ -92,10 +95,20 @@ export interface ITranslationService {
         await this.loadTranslation();
     }
 
+    /**
+     * Fired when the translation data has been loaded. Returns the translation language.
+     */
     public translationChanged(): Observable<string> {
         return this.translation.asObservable();
     }
 
+    /**
+     * Translates a key or an array of keys.
+     * @param keys The key or an array of keys to be translated
+     * @param args Optional parameters contained in the key
+     * @param lang The current language of the service is used by default
+     * @return The translated value or an object: {key: value}
+     */
     public translate(
         keys: string | string[],
         args: any = null,