Add code documentation (#10)

projects/ngx-xapi/client/src/lib/language-map/format-language-map.ts

@@ -1,5 +1,18 @@
 import { LanguageMap } from '@berry-cloud/ngx-xapi/model';
 
+/**
+ * Calculates the most appropriate language map value for the given locale.
+ *
+ * The algorithm is as follows:
+ * 1. If the locale is found in the language map, return the value.
+ * 2. If the locale has a subtag, remove the subtag and try again.
+ * 3. If the UND locale is found in the language map, return the value.
+ * 4. Return the first value in the language map or an empty string.
+ *
+ * @param languageMap a language map
+ * @param locale the preferred locale
+ * @returns the most appropriate language map value
+ */
 export function formatLanguageMap(
   languageMap: LanguageMap,
   locale: string

projects/ngx-xapi/client/src/lib/language-map/language-map.pipe.ts

@@ -2,32 +2,57 @@ import { Inject, LOCALE_ID, Pipe, PipeTransform } from '@angular/core';
 import { LanguageMap } from '@berry-cloud/ngx-xapi/model';
 import { formatLanguageMap } from './format-language-map';
 
+/**
+ * This pipe transforms the parameter (potentially a language map) into a string.
+ *
+ * @remarks
+ * If the parameter is a string, it is returned as is.
+ *
+ * If the parameter is a language map, the most appropriate value is returned.
+ *
+ * If the parameter is an array of language maps, the most appropriate value of each language map is concatenated.
+ *
+ * If the parameter is an array of strings, the strings are concatenated.
+ *
+ * If the parameter is an array of language maps and strings, the most appropriate value of each language map and the strings are concatenated.
+ *
+ * @param parameter a string or a language map or an array of language maps or an array of strings
+ * @param htmlConversion if true, the spaces and new lines in the returned string are converted to HTML tags
+ *
+ * @returns a string
+ *
+ * @example
+ * <p>{{ 'Hello World' | languageMap }}</p>
+ * <p>{{ { en: 'Hello World' } | languageMap }}</p>
+ * <p>{{ { en: 'Hello World', fr: 'Bonjour le monde' } | languageMap:false }}</p>
+ *
+ */
 @Pipe({
   name: 'languageMap',
 })
 export class LanguageMapPipe implements PipeTransform {
   constructor(@Inject(LOCALE_ID) private locale: string) {}
 
   transform(
-    languageMap: string | LanguageMap | (string | LanguageMap)[] | undefined,
+    parameter: string | LanguageMap | (string | LanguageMap)[] | undefined,
     htmlConversion = true
   ): string | null {
-    if (typeof languageMap == 'string') {
-      return languageMap;
+    if (typeof parameter == 'string') {
+      return parameter;
     }
-    if (!languageMap || Object.keys(languageMap).length === 0) {
+    if (!parameter || Object.keys(parameter).length === 0) {
       return null;
     }
     let text = '';
-    if (Array.isArray(languageMap)) {
-      if (languageMap.length == 0) {
+    if (Array.isArray(parameter)) {
+      if (parameter.length == 0) {
         return null;
       }
-      for (const lm of languageMap) {
+      for (const lm of parameter) {
         text += this.transform(lm);
       }
     } else {
-      text = formatLanguageMap(languageMap, this.locale);
+      text = formatLanguageMap(parameter, this.locale);
     }
 
     if (htmlConversion) {

projects/ngx-xapi/client/src/lib/statements.ts

@@ -1,11 +1,15 @@
 import { v4 as uuidv4 } from 'uuid';
-import { Verbs } from './verbs';
 import {
   Activity,
   Agent,
   Context,
   Statement,
   Verb,
+  completed,
+  initialized,
+  progressed,
+  registered,
+  terminated,
 } from '@berry-cloud/ngx-xapi/model';
 
 export class Statements {
@@ -27,7 +31,7 @@ export class Statements {
     return {
       id: uuidv4().toString(), // Registration might not be unique
       actor: agent,
-      verb: Verbs.registered,
+      verb: registered,
       object: activity,
       timestamp: timestamp?.toISOString() || new Date().toISOString(),
       context: { registration },
@@ -52,7 +56,7 @@ export class Statements {
   ): Statement {
     return this.statement(
       agent,
-      Verbs.initialized,
+      initialized,
       activity,
       context,
       registration,
@@ -80,7 +84,7 @@ export class Statements {
   ): Statement {
     const statement = this.statement(
       agent,
-      Verbs.completed,
+      completed,
       activity,
       context,
       registration,
@@ -112,7 +116,7 @@ export class Statements {
   ): Statement {
     const statement = this.statement(
       agent,
-      Verbs.terminated,
+      terminated,
       activity,
       context,
       registration,
@@ -144,7 +148,7 @@ export class Statements {
   ): Statement {
     const statement = this.statement(
       agent,
-      Verbs.progressed,
+      progressed,
       activity,
       context,
       registration,

projects/ngx-xapi/client/src/public-api.ts

@@ -10,4 +10,3 @@ export * from './lib/lrs-client';
 export * from './lib/state-params';
 export * from './lib/statements-params';
 export * from './lib/statements';
-export * from './lib/verbs';

projects/ngx-xapi/model/src/lib/about.ts

@@ -1,5 +1,10 @@
 import { Extensions } from './extensions';
 
+/**
+ * This interface represents the xAPI About object.
+ *
+ * @see {@link https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Communication.md#24-agents-resource | xAPI About}
+ */
 export interface About {
   version: string[];
   extensions?: Extensions;

projects/ngx-xapi/model/src/lib/account.ts

@@ -1,4 +1,16 @@
+/**
+ * This interface represents the xAPI Account object.
+ *
+ * @see {@link https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#2424-account-object | xAPI Account }
+ */
 export interface Account {
-  homePage?: string;
-  name?: string;
+  /**
+   * The canonical home page for the system the account is on.
+   */
+  homePage: string;
+
+  /**
+   * The unique id or name used to log in to this account.
+   */
+  name: string;
 }