MOBILE-4690 quiz: Review and improve some jsdocs

src/addons/mod/quiz/accessrules/password/services/handlers/password.ts

@@ -32,14 +32,7 @@ export class AddonModQuizAccessPasswordHandlerService implements AddonModQuizAcc
     ruleName = 'quizaccess_password';
 
     /**
-     * Add preflight data that doesn't require user interaction. The data should be added to the preflightData param.
-     *
-     * @param quiz The quiz the rule belongs to.
-     * @param preflightData Object where to add the preflight data.
-     * @param attempt The attempt started/continued. If not supplied, user is starting a new attempt.
-     * @param prefetch Whether the user is prefetching the quiz.
-     * @param siteId Site ID. If not defined, current site.
-     * @returns Promise resolved when done if async, void if it's synchronous.
+     * @inheritdoc
      */
     async getFixedPreflightData(
         quiz: AddonModQuizQuizWSData,
@@ -76,33 +69,21 @@ export class AddonModQuizAccessPasswordHandlerService implements AddonModQuizAcc
     }
 
     /**
-     * Return the Component to use to display the access rule preflight.
-     * Implement this if your access rule requires a preflight check with user interaction.
-     * It's recommended to return the class of the component, but you can also return an instance of the component.
-     *
-     * @returns The component (or promise resolved with component) to use, undefined if not found.
+     * @inheritdoc
      */
     getPreflightComponent(): Type<unknown> | Promise<Type<unknown>> {
         return AddonModQuizAccessPasswordComponent;
     }
 
     /**
-     * Whether or not the handler is enabled on a site level.
-     *
-     * @returns True or promise resolved with true if enabled.
+     * @inheritdoc
      */
     async isEnabled(): Promise<boolean> {
         return true;
     }
 
     /**
-     * Whether the rule requires a preflight check when prefetch/start/continue an attempt.
-     *
-     * @param quiz The quiz the rule belongs to.
-     * @param attempt The attempt started/continued. If not supplied, user is starting a new attempt.
-     * @param prefetch Whether the user is prefetching the quiz.
-     * @param siteId Site ID. If not defined, current site.
-     * @returns Whether the rule requires a preflight check.
+     * @inheritdoc
      */
     async isPreflightCheckRequired(
         quiz: AddonModQuizQuizWSData,
@@ -117,14 +98,7 @@ export class AddonModQuizAccessPasswordHandlerService implements AddonModQuizAcc
     }
 
     /**
-     * Function called when the preflight check has passed. This is a chance to record that fact in some way.
-     *
-     * @param quiz The quiz the rule belongs to.
-     * @param attempt The attempt started/continued.
-     * @param preflightData Preflight data gathered.
-     * @param prefetch Whether the user is prefetching the quiz.
-     * @param siteId Site ID. If not defined, current site.
-     * @returns Promise resolved when done if async, void if it's synchronous.
+     * @inheritdoc
      */
     async notifyPreflightCheckPassed(
         quiz: AddonModQuizQuizWSData,
@@ -135,37 +109,29 @@ export class AddonModQuizAccessPasswordHandlerService implements AddonModQuizAcc
     ): Promise<void> {
         // The password is right, store it to use it automatically in following executions.
         if (preflightData.quizpassword !== undefined) {
-            return this.storePassword(quiz.id, preflightData.quizpassword, siteId);
+            await this.storePassword(quiz.id, preflightData.quizpassword, siteId);
         }
     }
 
     /**
-     * Function called when the preflight check fails. This is a chance to record that fact in some way.
-     *
-     * @param quiz The quiz the rule belongs to.
-     * @param attempt The attempt started/continued.
-     * @param preflightData Preflight data gathered.
-     * @param prefetch Whether the user is prefetching the quiz.
-     * @param siteId Site ID. If not defined, current site.
-     * @returns Promise resolved when done if async, void if it's synchronous.
+     * @inheritdoc
      */
-    notifyPreflightCheckFailed?(
+    async notifyPreflightCheckFailed?(
         quiz: AddonModQuizQuizWSData,
         attempt: AddonModQuizAttemptWSData | undefined,
         preflightData: Record<string, string>,
         prefetch?: boolean,
         siteId?: string,
     ): Promise<void> {
         // The password is wrong, remove it from DB if it's there.
-        return this.removePassword(quiz.id, siteId);
+        await this.removePassword(quiz.id, siteId);
     }
 
     /**
      * Remove a password from DB.
      *
      * @param quizId Quiz ID.
      * @param siteId Site ID. If not defined, current site.
-     * @returns Promise resolved when done.
      */
     protected async removePassword(quizId: number, siteId?: string): Promise<void> {
         const site = await CoreSites.getSite(siteId);
@@ -179,7 +145,6 @@ export class AddonModQuizAccessPasswordHandlerService implements AddonModQuizAcc
      * @param quizId Quiz ID.
      * @param password Password.
      * @param siteId Site ID. If not defined, current site.
-     * @returns Promise resolved when done.
      */
     protected async storePassword(quizId: number, password: string, siteId?: string): Promise<void> {
         const site = await CoreSites.getSite(siteId);

src/addons/mod/quiz/components/index/index.ts

@@ -130,8 +130,6 @@ export class AddonModQuizIndexComponent extends CoreCourseModuleMainActivityComp
 
     /**
      * Attempt the quiz.
-     *
-     * @returns Promise resolved when done.
      */
     async attemptQuiz(): Promise<void> {
         if (this.showStatusSpinner || !this.quiz) {
@@ -141,7 +139,9 @@ export class AddonModQuizIndexComponent extends CoreCourseModuleMainActivityComp
 
         if (!AddonModQuiz.isOfflineSupported(this.quiz)) {
             // Quiz isn't offline, just open it.
-            return this.openQuiz();
+            this.openQuiz();
+
+            return;
         }
 
         // Quiz supports offline, check if it needs to be downloaded.
@@ -150,7 +150,9 @@ export class AddonModQuizIndexComponent extends CoreCourseModuleMainActivityComp
 
         if (isDownloaded) {
             // Already downloaded, open it.
-            return this.openQuiz();
+            this.openQuiz();
+
+            return;
         }
 
         // Prefetch the quiz.
@@ -242,7 +244,6 @@ export class AddonModQuizIndexComponent extends CoreCourseModuleMainActivityComp
      * Get the user attempts in the quiz and the result info.
      *
      * @param quiz Quiz instance.
-     * @returns Promise resolved when done.
      */
     protected async getAttempts(
         quiz: AddonModQuizQuizData,
@@ -326,7 +327,6 @@ export class AddonModQuizIndexComponent extends CoreCourseModuleMainActivityComp
      * Get result info to show.
      *
      * @param quiz Quiz.
-     * @returns Promise resolved when done.
      */
     protected async getResultInfo(quiz: AddonModQuizQuizData): Promise<void> {
         if (!this.attempts.length || !quiz.showAttemptsGrades || !this.bestGrade?.hasgrade ||
@@ -382,8 +382,6 @@ export class AddonModQuizIndexComponent extends CoreCourseModuleMainActivityComp
 
     /**
      * Go to review an attempt that has just been finished.
-     *
-     * @returns Promise resolved when done.
      */
     protected async goToAutoReview(attempts: AddonModQuizAttemptWSData[]): Promise<void> {
         if (!this.autoReview) {
@@ -505,10 +503,10 @@ export class AddonModQuizIndexComponent extends CoreCourseModuleMainActivityComp
     /**
      * Open a quiz to attempt it.
      */
-    protected openQuiz(): void {
+    protected async openQuiz(): Promise<void> {
         this.hasPlayed = true;
 
-        CoreNavigator.navigateToSitePath(
+        await CoreNavigator.navigateToSitePath(
             `${ADDON_MOD_QUIZ_PAGE_NAME}/${this.courseId}/${this.module.id}/player`,
             {
                 params: {
@@ -554,7 +552,7 @@ export class AddonModQuizIndexComponent extends CoreCourseModuleMainActivityComp
      * @param quiz Quiz data.
      * @param accessInfo Quiz access information.
      * @param attempts The attempts to treat.
-     * @returns Promise resolved when done.
+     * @returns Formatted attempts.
      */
     protected async treatAttempts(
         quiz: AddonModQuizQuizData,
@@ -630,8 +628,6 @@ export class AddonModQuizIndexComponent extends CoreCourseModuleMainActivityComp
 
     /**
      * Get quiz grade data.
-     *
-     * @returns Promise resolved when done.
      */
     protected async getQuizGrade(): Promise<void> {
         try {
@@ -656,8 +652,6 @@ export class AddonModQuizIndexComponent extends CoreCourseModuleMainActivityComp
 
     /**
      * Go to page to review the attempt.
-     *
-     * @returns Promise resolved when done.
      */
     async reviewAttempt(attemptId: number): Promise<void> {
         await CoreNavigator.navigateToSitePath(

src/addons/mod/quiz/pages/player/player.ts

@@ -556,7 +556,6 @@ export class AddonModQuizPlayerPage implements OnInit, OnDestroy, CanLeave {
      * Load a page questions.
      *
      * @param page The page to load.
-     * @returns Promise resolved when done.
      */
     protected async loadPage(page: number): Promise<void> {
         if (!this.quiz || !this.attempt) {

src/addons/mod/quiz/pages/review/review.ts

@@ -144,8 +144,6 @@ export class AddonModQuizReviewPage implements OnInit {
 
     /**
      * Convenience function to get the quiz data.
-     *
-     * @returns Promise resolved when done.
      */
     protected async fetchData(): Promise<void> {
         try {
@@ -171,7 +169,6 @@ export class AddonModQuizReviewPage implements OnInit {
      * Load a page questions.
      *
      * @param page The page to load.
-     * @returns Promise resolved when done.
      */
     protected async loadPage(page: number): Promise<void> {
         if (!this.quiz) {
@@ -200,8 +197,6 @@ export class AddonModQuizReviewPage implements OnInit {
 
     /**
      * Load data to navigate the questions using the navigation modal.
-     *
-     * @returns Promise resolved when done.
      */
     protected async loadNavigation(): Promise<void> {
         // Get all questions in single page to retrieve all the questions.

src/addons/mod/quiz/services/access-rules-delegate.ts

@@ -256,7 +256,6 @@ export class AddonModQuizAccessRuleDelegateService extends CoreDelegate<AddonMod
      * @param preflightData Preflight data gathered.
      * @param prefetch Whether the user is prefetching the quiz.
      * @param siteId Site ID. If not defined, current site.
-     * @returns Promise resolved when done.
      */
     async notifyPreflightCheckPassed(
         rules: string[],
@@ -286,7 +285,6 @@ export class AddonModQuizAccessRuleDelegateService extends CoreDelegate<AddonMod
      * @param preflightData Preflight data gathered.
      * @param prefetch Whether the user is prefetching the quiz.
      * @param siteId Site ID. If not defined, current site.
-     * @returns Promise resolved when done.
      */
     async notifyPreflightCheckFailed(
         rules: string[],

src/addons/mod/quiz/services/handlers/prefetch.ts

@@ -248,23 +248,14 @@ export class AddonModQuizPrefetchHandlerService extends CoreCourseActivityPrefet
     }
 
     /**
-     * Whether or not the handler is enabled on a site level.
-     *
-     * @returns A boolean, or a promise resolved with a boolean, indicating if the handler is enabled.
+     * @inheritdoc
      */
     async isEnabled(): Promise<boolean> {
         return true;
     }
 
     /**
-     * Prefetch a module.
-     *
-     * @param module Module.
-     * @param courseId Course ID the module belongs to.
-     * @param single True if we're downloading a single module, false if we're downloading a whole section.
-     * @param dirPath Path of the directory where to store all the content files.
-     * @param canStart If true, start a new attempt if needed.
-     * @returns Promise resolved when done.
+     * @inheritdoc
      */
     async prefetch(
         module: SyncedModule,
@@ -292,7 +283,6 @@ export class AddonModQuizPrefetchHandlerService extends CoreCourseActivityPrefet
      * @param single True if we're downloading a single module, false if we're downloading a whole section.
      * @param canStart If true, start a new attempt if needed.
      * @param siteId Site ID.
-     * @returns Promise resolved when done.
      */
     protected async prefetchQuiz(
         module: CoreCourseAnyModuleData,
@@ -474,7 +464,6 @@ export class AddonModQuizPrefetchHandlerService extends CoreCourseActivityPrefet
      * @param accessInfo Quiz access info.
      * @param attempt Attempt.
      * @param modOptions Other options.
-     * @returns Promise resolved when done.
      */
     protected async prefetchAttemptReview(
         quiz: AddonModQuizQuizWSData,
@@ -511,7 +500,6 @@ export class AddonModQuizPrefetchHandlerService extends CoreCourseActivityPrefet
      * @param quiz Quiz.
      * @param attempt Attempt.
      * @param modOptions Other options.
-     * @returns Promise resolved when done.
      */
     protected async prefetchAttemptReviewFiles(
         quiz: AddonModQuizQuizWSData,
@@ -545,7 +533,6 @@ export class AddonModQuizPrefetchHandlerService extends CoreCourseActivityPrefet
      * @param quiz Quiz.
      * @param modOptions Other options.
      * @param siteId Site ID.
-     * @returns Promise resolved when done.
      */
     protected async prefetchGradeAndFeedback(
         quiz: AddonModQuizQuizWSData,
@@ -570,7 +557,6 @@ export class AddonModQuizPrefetchHandlerService extends CoreCourseActivityPrefet
      * @param quiz Quiz.
      * @param askPreflight Whether it should ask for preflight data if needed.
      * @param siteId Site ID. If not defined, current site.
-     * @returns Promise resolved when done.
      */
     async prefetchQuizAndLastAttempt(quiz: AddonModQuizQuizWSData, askPreflight?: boolean, siteId?: string): Promise<void> {
         siteId = siteId || CoreSites.getCurrentSiteId();
@@ -617,7 +603,6 @@ export class AddonModQuizPrefetchHandlerService extends CoreCourseActivityPrefet
      *
      * @param quiz Quiz.
      * @param options Other options.
-     * @returns Promise resolved when done.
      */
     async setStatusAfterPrefetch(
         quiz: AddonModQuizQuizWSData,
@@ -654,7 +639,7 @@ export class AddonModQuizPrefetchHandlerService extends CoreCourseActivityPrefet
      * @param module Module.
      * @param courseId Course ID the module belongs to
      * @param siteId Site ID. If not defined, current site.
-     * @returns Promise resolved when done.
+     * @returns Sync results.
      */
     async sync(module: SyncedModule, courseId: number, siteId?: string): Promise<AddonModQuizSyncResult | undefined> {
         const quiz = await AddonModQuiz.getQuiz(courseId, module.id, { siteId });

src/addons/mod/quiz/services/handlers/push-click.ts

@@ -39,10 +39,7 @@ export class AddonModQuizPushClickHandlerService implements CorePushNotification
     protected readonly SUPPORTED_NAMES = ['submission', 'confirmation', 'attempt_overdue'];
 
     /**
-     * Check if a notification click is handled by this handler.
-     *
-     * @param notification The notification to check.
-     * @returns Whether the notification click is handled by this handler
+     * @inheritdoc
      */
     async handles(notification: AddonModQuizPushNotificationData): Promise<boolean> {
         return CoreUtils.isTrueOrOne(notification.notif) && notification.moodlecomponent == 'mod_quiz' &&
@@ -51,10 +48,7 @@ export class AddonModQuizPushClickHandlerService implements CorePushNotification
     }
 
     /**
-     * Handle the notification click.
-     *
-     * @param notification The notification to check.
-     * @returns Promise resolved when done.
+     * @inheritdoc
      */
     async handleClick(notification: AddonModQuizPushNotificationData): Promise<void> {
         const contextUrlParams = CoreUrl.extractUrlParams(notification.contexturl || '');
@@ -68,12 +62,14 @@ export class AddonModQuizPushClickHandlerService implements CorePushNotification
             contextUrlParams.page !== undefined
         ) {
             // A student made a submission, go to view the attempt.
-            return AddonModQuizHelper.handleReviewLink(
+            await AddonModQuizHelper.handleReviewLink(
                 Number(contextUrlParams.attempt),
                 Number(contextUrlParams.page),
                 Number(data.instance),
                 notification.site,
             );
+
+            return;
         }
 
         // Open the activity.
@@ -84,7 +80,7 @@ export class AddonModQuizPushClickHandlerService implements CorePushNotification
 
         await CorePromiseUtils.ignoreErrors(AddonModQuiz.invalidateContent(moduleId, courseId, notification.site));
 
-        return CoreCourseHelper.navigateToModule(moduleId, {
+        await CoreCourseHelper.navigateToModule(moduleId, {
             courseId,
             siteId: notification.site,
         });