Add jsdoc comments for user verification, password reprompt, and appApiAction (#754)

* Rename and add comments to clarify password reprompt classes

* Add comment for appApiAction

angular/src/components/password-reprompt.component.ts

@@ -6,6 +6,10 @@ import { PlatformUtilsService } from "jslib-common/abstractions/platformUtils.se
 
 import { ModalRef } from "./modal/modal.ref";
 
+/**
+ * Used to verify the user's Master Password for the "Master Password Re-prompt" feature only.
+ * See UserVerificationComponent for any other situation where you need to verify the user's identity.
+ */
 @Directive()
 export class PasswordRepromptComponent {
   showPassword = false;

angular/src/components/user-verification.component.ts

@@ -7,14 +7,20 @@ import { UserVerificationService } from "jslib-common/abstractions/userVerificat
 import { VerificationType } from "jslib-common/enums/verificationType";
 import { Verification } from "jslib-common/types/verification";
 
+/**
+ * Used for general-purpose user verification throughout the app.
+ * Collects the user's master password, or if they are using Key Connector, prompts for an OTP via email.
+ * This is exposed to the parent component via the ControlValueAccessor interface (e.g. bind it to a FormControl).
+ * Use UserVerificationService to verify the user's input.
+ */
 @Component({
-  selector: "app-verify-master-password",
+  selector: "app-user-verification",
-  templateUrl: "verify-master-password.component.html",
+  templateUrl: "user-verification.component.html",
   providers: [
     {
       provide: NG_VALUE_ACCESSOR,
       multi: true,
-      useExisting: VerifyMasterPasswordComponent,
+      useExisting: UserVerificationComponent,
     },
   ],
   animations: [
@@ -23,7 +29,7 @@ import { Verification } from "jslib-common/types/verification";
     ]),
   ],
 })
-export class VerifyMasterPasswordComponent implements ControlValueAccessor, OnInit {
+export class UserVerificationComponent implements ControlValueAccessor, OnInit {
   usesKeyConnector = false;
   disableRequestOTP = false;
   sentCode = false;
@@ -41,7 +47,7 @@ export class VerifyMasterPasswordComponent implements ControlValueAccessor, OnIn
     this.usesKeyConnector = await this.keyConnectorService.getUsesKeyConnector();
     this.processChanges(this.secret.value);
 
-    this.secret.valueChanges.subscribe((secret) => this.processChanges(secret));
+    this.secret.valueChanges.subscribe((secret: string) => this.processChanges(secret));
   }
 
   async requestOTP() {

angular/src/directives/api-action.directive.ts

@@ -5,6 +5,12 @@ import { ErrorResponse } from "jslib-common/models/response/errorResponse";
 
 import { ValidationService } from "../services/validation.service";
 
+/**
+ * Provides error handling, in particular for any error returned by the server in an api call.
+ * Attach it to a <form> element and provide the name of the class property that will hold the api call promise.
+ * e.g. <form [appApiAction]="this.formPromise">
+ * Any errors/rejections that occur will be intercepted and displayed as error toasts.
+ */
 @Directive({
   selector: "[appApiAction]",
 })

angular/src/services/passwordReprompt.service.ts

@@ -7,6 +7,10 @@ import { PasswordRepromptComponent } from "../components/password-reprompt.compo
 
 import { ModalService } from "./modal.service";
 
+/**
+ * Used to verify the user's Master Password for the "Master Password Re-prompt" feature only.
+ * See UserVerificationService for any other situation where you need to verify the user's identity.
+ */
 @Injectable()
 export class PasswordRepromptService implements PasswordRepromptServiceAbstraction {
   protected component = PasswordRepromptComponent;

common/src/services/userVerification.service.ts

@@ -7,6 +7,10 @@ import { VerifyOTPRequest } from "../models/request/account/verifyOTPRequest";
 import { SecretVerificationRequest } from "../models/request/secretVerificationRequest";
 import { Verification } from "../types/verification";
 
+/**
+ * Used for general-purpose user verification throughout the app.
+ * Use it to verify the input collected by UserVerificationComponent.
+ */
 export class UserVerificationService implements UserVerificationServiceAbstraction {
   constructor(
     private cryptoService: CryptoService,
@@ -14,6 +18,12 @@ export class UserVerificationService implements UserVerificationServiceAbstracti
     private apiService: ApiService
   ) {}
 
+  /**
+   * Create a new request model to be used for server-side verification
+   * @param verification User-supplied verification data (Master Password or OTP)
+   * @param requestClass The request model to create
+   * @param alreadyHashed Whether the master password is already hashed
+   */
   async buildRequest<T extends SecretVerificationRequest>(
     verification: Verification,
     requestClass?: new () => T,
@@ -35,6 +45,11 @@ export class UserVerificationService implements UserVerificationServiceAbstracti
     return request;
   }
 
+  /**
+   * Used to verify the Master Password client-side, or send the OTP to the server for verification (with no other data)
+   * Generally used for client-side verification only.
+   * @param verification User-supplied verification data (Master Password or OTP)
+   */
   async verifyUser(verification: Verification): Promise<boolean> {
     this.validateInput(verification);