MOBILE-3947 lint: Fix jsdocs

src/app/app.module.ts

@@ -34,7 +34,12 @@ import { CoreSiteInfoCronHandler } from '@services/handlers/site-info-cron';
 import { moodleTransitionAnimation } from '@classes/page-transition';
 import { TestingModule } from '@/testing/testing.module';
 
-// For translate loader. AoT requires an exported function for factories.
+/**
+ * For translate loader. AoT requires an exported function for factories.
+ *
+ * @param http Http client.
+ * @returns Translate loader.
+ */
 export function createTranslateLoader(http: HttpClient): TranslateHttpLoader {
     return new TranslateHttpLoader(http, './assets/lang/', '.json');
 }

src/core/classes/tests/database-table.test.ts

@@ -24,10 +24,24 @@ type User = {
     surname: string;
 };
 
+/**
+ * Checks if a user object matches specified conditions.
+ *
+ * @param user The user object to be checked.
+ * @param conditions The conditions to match against the user object.
+ * @returns Returns true if the user matches the conditions, false otherwise.
+ */
 function userMatches(user: User, conditions: Partial<User>) {
     return !Object.entries(conditions).some(([column, value]) => user[column] !== value);
 }
 
+/**
+ * Prepares stubs for testing with a mock database configuration.
+ *
+ * @param config The partial CoreDatabaseConfiguration to use for the mock database.
+ * @returns An array containing a mock user records array, a mock SQLite database,
+ * and a CoreDatabaseTable instance for the 'users' table.
+ */
 function prepareStubs(config: Partial<CoreDatabaseConfiguration> = {}): [User[], SQLiteDB, CoreDatabaseTable<User>] {
     const records: User[] = [];
     const database = mock<SQLiteDB>({
@@ -68,6 +82,12 @@ function prepareStubs(config: Partial<CoreDatabaseConfiguration> = {}): [User[],
     return [records, database, table];
 }
 
+/**
+ * Test function for finding items in the database.
+ *
+ * @param records An array of user records to use for testing.
+ * @param table The CoreDatabaseTable instance to test.
+ */
 async function testFindItems(records: User[], table: CoreDatabaseTable<User>) {
     const john = { id: 1, name: 'John', surname: 'Doe' };
     const amy = { id: 2, name: 'Amy', surname: 'Doe' };
@@ -83,6 +103,13 @@ async function testFindItems(records: User[], table: CoreDatabaseTable<User>) {
     await expect(table.getOneByPrimaryKey({ id: 2 })).resolves.toEqual(amy);
 }
 
+/**
+ * Tests the insertion of items into a database table.
+ *
+ * @param records An array of User records.
+ * @param database The SQLite database instance.
+ * @param table The database table instance.
+ */
 async function testInsertItems(records: User[], database: SQLiteDB, table: CoreDatabaseTable<User>) {
     // Arrange.
     const john = { id: 1, name: 'John', surname: 'Doe' };
@@ -98,6 +125,13 @@ async function testInsertItems(records: User[], database: SQLiteDB, table: CoreD
     await expect(table.getOneByPrimaryKey({ id: 1 })).resolves.toEqual(john);
 }
 
+/**
+ * Tests the deletion of items from a database table based on a condition.
+ *
+ * @param records An array of User records.
+ * @param database The SQLite database instance.
+ * @param table The database table instance.
+ */
 async function testDeleteItems(records: User[], database: SQLiteDB, table: CoreDatabaseTable<User>) {
     // Arrange.
     const john = { id: 1, name: 'John', surname: 'Doe' };
@@ -121,6 +155,13 @@ async function testDeleteItems(records: User[], database: SQLiteDB, table: CoreD
     await expect(table.getOneByPrimaryKey({ id: 3 })).resolves.toEqual(jane);
 }
 
+/**
+ * Tests the deletion of items from a database table based on primary key values.
+ *
+ * @param records An array of User records.
+ * @param database The SQLite database instance.
+ * @param table The database table instance.
+ */
 async function testDeleteItemsByPrimaryKey(records: User[], database: SQLiteDB, table: CoreDatabaseTable<User>) {
     // Arrange.
     const john = { id: 1, name: 'John', surname: 'Doe' };

src/core/features/editor/components/rich-text-editor/rich-text-editor.ts

@@ -656,8 +656,8 @@ export class CoreEditorRichTextEditorComponent implements OnInit, AfterViewInit,
     /**
      * Replace tags for a11y.
      *
-     * @param originTag      Origin tags to be replaced.
-     * @param destinationTag Destination tags to replace.
+     * @param originTags      Origin tags to be replaced.
+     * @param destinationTags Destination tags to replace.
      */
     protected replaceTags(originTags: string[], destinationTags: string[]): void {
         if (!this.editorElement) {

src/core/initializers/clear-tmp-folder.ts

@@ -14,6 +14,9 @@
 
 import { CoreFile } from '@services/file';
 
+/**
+ * Clears the temporary folder.
+ */
 export default async function(): Promise<void> {
     await CoreFile.clearTmpFolder();
 }

src/core/initializers/consume-storage-redirect.ts

@@ -15,6 +15,9 @@
 import { CoreApp } from '@services/app';
 import { CoreUpdateManager } from '@services/update-manager';
 
+/**
+ * Read redirect data from local storage and clear it if it existed.
+ */
 export default async function(): Promise<void> {
     await CoreUpdateManager.donePromise;
 

src/core/initializers/index.ts

@@ -14,6 +14,12 @@
 
 import { APP_INITIALIZER, Provider } from '@angular/core';
 
+/**
+ * Get the providers for the initializers.
+ * Please use the APP_INITIALIZER token to provide the initializers.
+ *
+ * @returns List of providers.
+ */
 export function getInitializerProviders(): Provider[] {
     const context = require.context('./', false, /\.ts$/);
 

src/core/initializers/initialize-services.ts

@@ -22,6 +22,9 @@ import { CoreSites } from '@services/sites';
 import { CoreUpdateManager } from '@services/update-manager';
 import { CoreTimeUtils } from '@services/utils/time';
 
+/**
+ * Initializes various core components asynchronously.
+ */
 export default async function(): Promise<void> {
     await Promise.all([
         CoreConfig.initialize(),

src/core/initializers/initialize-urlscheme.ts

@@ -16,6 +16,9 @@ import { CoreCustomURLSchemes } from '@services/urlschemes';
 import { NgZone } from '@singletons';
 import { CoreEvents } from '@singletons/events';
 
+/**
+ * Asynchronous function to handle custom URLs when the app is launched.
+ */
 export default async function(): Promise<void> {
     const lastUrls: Record<string, number> = {};
 

src/core/initializers/initialize-user-agent.ts

@@ -15,6 +15,9 @@
 import { CorePlatform } from '@services/platform';
 import { NativeHttp } from '@singletons';
 
+/**
+ * This function sets the User-Agent header using NativeHttp for mobile platform.
+ */
 export default async function(): Promise<void> {
     if (!CorePlatform.isMobile()) {
         return;

src/core/initializers/override-window-open.ts

@@ -14,7 +14,10 @@
 
 import { CorePlatform } from '@services/platform';
 
-export default async function(): Promise<void> {
+/**
+ * Initializes the application and sets up the InAppBrowser if available.
+ */
+export default async function initializeApp(): Promise<void> {
     await CorePlatform.ready();
 
     if (!window.cordova?.InAppBrowser) {

src/core/initializers/prepare-devtools.ts

@@ -29,6 +29,11 @@ type DevelopmentWindow = Window & {
     pushNotifications?: CorePushNotificationsProvider;
 };
 
+/**
+ * Initializes the development window with necessary providers and configurations.
+ *
+ * @param window The development window object to be initialized.
+ */
 function initializeDevelopmentWindow(window: DevelopmentWindow) {
     window.browser = CoreBrowser;
     window.appProvider = CoreApp.instance;
@@ -38,6 +43,9 @@ function initializeDevelopmentWindow(window: DevelopmentWindow) {
     window.pushNotifications = CorePushNotifications.instance;
 }
 
+/**
+ * Initializes the development tools if enabled by CoreConstants.
+ */
 export default function(): void {
     if (!CoreConstants.enableDevTools()) {
         return;

src/core/initializers/restore-session.ts

@@ -15,6 +15,9 @@
 import { CoreSites } from '@services/sites';
 import { CoreUpdateManager } from '@services/update-manager';
 
+/**
+ * Restores the session to the previous one so the user doesn't has to login everytime the app is started.
+ */
 export default async function(): Promise<void> {
     await CoreUpdateManager.donePromise;
 

src/core/initializers/subscribe-to-keyboard-events.ts

@@ -15,6 +15,9 @@
 import { CoreApp } from '@services/app';
 import { NgZone, Keyboard } from '@singletons';
 
+/**
+ * Initializes keyboard event listeners and ensures Angular zone is properly managed for change detection.
+ */
 export default function(): void {
     const zone = NgZone.instance;
     const app = CoreApp.instance;

src/core/initializers/wait-for-platform-ready.ts

@@ -14,6 +14,9 @@
 
 import { CorePlatform } from '@services/platform';
 
+/**
+ * Initializes the application when the CorePlatform is ready.
+ */
 export default async function(): Promise<void> {
     await CorePlatform.ready();
 }

src/core/initializers/watch-screen-status.ts

@@ -14,6 +14,10 @@
 
 import { CoreScreen } from '@services/screen';
 
+/**
+ * Initializes the application by watching the viewport and orientation changes.
+ * This function should be called to set up necessary event listeners for proper functionality.
+ */
 export default function(): void {
     CoreScreen.watchViewport();
 

src/core/utils/rxjs.ts

@@ -77,6 +77,8 @@ export function asyncObservable<T>(createObservable: () => Promise<Observable<T>
     });
 }
 
+export function ignoreErrors<Result>(observable: Observable<Result>): Observable<Result | undefined>;
+export function ignoreErrors<Result, Fallback>(observable: Observable<Result>, fallback: Fallback): Observable<Result | Fallback>;
 /**
  * Ignore errors from an observable, returning a certain value instead.
  *
@@ -84,8 +86,6 @@ export function asyncObservable<T>(createObservable: () => Promise<Observable<T>
  * @param fallback Value to return if the observer errors.
  * @returns Observable with ignored errors, returning the fallback result if provided.
  */
-export function ignoreErrors<Result>(observable: Observable<Result>): Observable<Result | undefined>;
-export function ignoreErrors<Result, Fallback>(observable: Observable<Result>, fallback: Fallback): Observable<Result | Fallback>;
 export function ignoreErrors<Result, Fallback>(
     observable: Observable<Result>,
     fallback?: Fallback,

src/testing/testing.module.ts

@@ -21,6 +21,11 @@ type AutomatedTestsWindow = Window & {
     behat?: TestingBehatRuntimeService;
 };
 
+/**
+ * Initialize automated tests.
+ *
+ * @param window Window.
+ */
 function initializeAutomatedTests(window: AutomatedTestsWindow) {
     if (!CoreAppProvider.isAutomated()) {
         return;

src/testing/utils.ts

@@ -80,6 +80,13 @@ const DEFAULT_SERVICE_SINGLETON_MOCKS: [CoreSingletonProxy, unknown][] = [
     })],
 ];
 
+/**
+ * Renders an Angular component for testing.
+ *
+ * @param component The Angular component to render.
+ * @param config Configuration options for rendering.
+ * @returns A promise that resolves to the testing component fixture.
+ */
 async function renderAngularComponent<T>(component: Type<T>, config: RenderConfig): Promise<TestingComponentFixture<T>> {
     config.declarations.push(component);
 
@@ -114,6 +121,13 @@ async function renderAngularComponent<T>(component: Type<T>, config: RenderConfi
     return fixture;
 }
 
+/**
+ * Creates a wrapper component for testing.
+ *
+ * @param template The template for the wrapper component.
+ * @param componentClass The class of the component to be wrapped.
+ * @returns The wrapper component class.
+ */
 function createWrapperComponent<U>(template: string, componentClass: Type<U>): Type<WrapperComponent<U>> {
     @Component({ template })
     class HostComponent extends WrapperComponent<U> {
@@ -125,6 +139,11 @@ function createWrapperComponent<U>(template: string, componentClass: Type<U>): T
     return HostComponent;
 }
 
+/**
+ * Gets the default declarations for testing.
+ *
+ * @returns An array of default declarations.
+ */
 function getDefaultDeclarations(): unknown[] {
     return [
         TranslatePipeStub,
@@ -132,6 +151,12 @@ function getDefaultDeclarations(): unknown[] {
     ];
 }
 
+/**
+ * Gets the default providers for testing.
+ *
+ * @param config Configuration options for rendering.
+ * @returns An array of default providers.
+ */
 function getDefaultProviders(config: RenderConfig): unknown[] {
     const serviceProviders = DEFAULT_SERVICE_SINGLETON_MOCKS.map(
         ([singleton, mockInstance]) => ({
@@ -159,6 +184,12 @@ function getDefaultProviders(config: RenderConfig): unknown[] {
     ];
 }
 
+/**
+ * Resolves a service instance from the TestBed.
+ *
+ * @param injectionToken The injection token for the service.
+ * @returns The service instance or null if not found.
+ */
 function resolveServiceInstanceFromTestBed(injectionToken: Exclude<ServiceInjectionToken, string>): Record<string, unknown> | null {
     if (!testBedInitialized) {
         return null;
@@ -167,6 +198,12 @@ function resolveServiceInstanceFromTestBed(injectionToken: Exclude<ServiceInject
     return TestBed.inject(injectionToken) as Record<string, unknown> | null;
 }
 
+/**
+ * Creates a new instance of a service.
+ *
+ * @param injectionToken The injection token for the service.
+ * @returns The new service instance or null if an error occurs.
+ */
 function createNewServiceInstance(injectionToken: Exclude<ServiceInjectionToken, string>): Record<string, unknown> | null {
     try {
         const constructor = injectionToken as { new (): Record<string, unknown> };
@@ -192,6 +229,14 @@ export type TestingComponentFixture<T = unknown> = Omit<ComponentFixture<T>, 'na
 
 export type WrapperComponentFixture<T = unknown> = TestingComponentFixture<WrapperComponent<T>>;
 
+/**
+ * Finds an element in the fixture's native element.
+ *
+ * @param fixture The testing component fixture.
+ * @param selector The CSS selector for the element.
+ * @param content The text content or regular expression to match.
+ * @returns The element or null if not found.
+ */
 export function findElement<E = HTMLElement>(
     fixture: TestingComponentFixture,
     selector: string,
@@ -215,6 +260,14 @@ export function findElement<E = HTMLElement>(
     return null;
 }
 
+/**
+ * Requires an element in the fixture's native element.
+ *
+ * @param fixture The testing component fixture.
+ * @param selector The CSS selector for the element.
+ * @param content The text content or regular expression to match.
+ * @returns The element.
+ */
 export function requireElement<E = HTMLElement>(
     fixture: TestingComponentFixture,
     selector: string,
@@ -272,6 +325,15 @@ export function mockSingleton<T>(
     methods: string[],
     instance?: Record<string, unknown>,
 ): T;
+
+/**
+ * Mocks a singleton instance for testing purposes.
+ *
+ * @param singleton The singleton class or proxy.
+ * @param methodsOrProperties An array of method names to mock or an object containing property names and values.
+ * @param properties If `methodsOrProperties` is an array, this object contains the properties to mock.
+ * @returns The mocked singleton instance.
+ */
 export function mockSingleton<T>(
     singleton: CoreSingletonProxy<T>,
     methodsOrProperties: string[] | Record<string, unknown> = [],
@@ -299,6 +361,10 @@ export function mockSingleton<T>(
     return mockInstance;
 }
 
+/**
+ * Resets the testing environment by marking the test bed as uninitialized and
+ * restoring default service singleton mocks.
+ */
 export function resetTestingEnvironment(): void {
     testBedInitialized = false;
 
@@ -307,6 +373,15 @@ export function resetTestingEnvironment(): void {
     }
 }
 
+/**
+ * Retrieves the service instance corresponding to the provided injection token.
+ * If the injection token is a string, an empty object is returned.
+ * If the service instance is found in the test bed, it is returned.
+ * If not found, a new service instance is created, or an empty object is returned if creation fails.
+ *
+ * @param injectionToken The injection token for the desired service.
+ * @returns The service instance or an empty object.
+ */
 export function getServiceInstance(injectionToken: ServiceInjectionToken): Record<string, unknown> {
     if (typeof injectionToken === 'string') {
         return {};
@@ -317,6 +392,13 @@ export function getServiceInstance(injectionToken: ServiceInjectionToken): Recor
         ?? {};
 }
 
+/**
+ * Renders a component with the given configuration.
+ *
+ * @param component The Angular component to render.
+ * @param config Configuration options for rendering.
+ * @returns A promise that resolves to the testing component fixture.
+ */
 export async function renderComponent<T>(
     component: Type<T>,
     config: Partial<RenderConfig> = {},
@@ -329,6 +411,13 @@ export async function renderComponent<T>(
     });
 }
 
+/**
+ * Renders a page component with the given configuration.
+ *
+ * @param component The Angular component to render.
+ * @param config Configuration options for rendering a page component.
+ * @returns A promise that resolves to the testing component fixture.
+ */
 export async function renderPageComponent<T>(
     component: Type<T>,
     config: Partial<RenderPageConfig> = {},
@@ -347,6 +436,14 @@ export async function renderPageComponent<T>(
     return renderComponent(component, config);
 }
 
+/**
+ * Renders a template with the given configuration.
+ *
+ * @param component The Angular component to wrap in a template.
+ * @param template The template for the wrapper component.
+ * @param config Configuration options for rendering.
+ * @returns A promise that resolves to the wrapper component fixture.
+ */
 export async function renderTemplate<T>(
     component: Type<T>,
     template: string,
@@ -366,6 +463,15 @@ export async function renderTemplate<T>(
     );
 }
 
+/**
+ * Renders a wrapper component with the given configuration.
+ *
+ * @param component The Angular component to wrap.
+ * @param tag The HTML tag for the wrapper component.
+ * @param inputs Input attributes for the wrapper component.
+ * @param config Configuration options for rendering.
+ * @returns A promise that resolves to the wrapper component fixture.
+ */
 export async function renderWrapperComponent<T>(
     component: Type<T>,
     tag: string,
@@ -423,10 +529,21 @@ export function mockTranslate(translations: Record<string, string> = {}): void {
     });
 }
 
+/**
+ * Creates a test function that asserts that two types are equal.
+ *
+ * @param equal The equality check function for types A and B.
+ * @returns A test function that asserts equality.
+ */
 export function expectSameTypes<A, B>(equal: Equal<A, B>): () => void {
     return () => expect(equal).toBe(true);
 }
 
+/**
+ * Creates a test function that always asserts true, used for testing generic types.
+ *
+ * @returns A test function that always asserts true.
+ */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export function expectAnyType<T>(): () => void {
     return () => expect(true).toBe(true);