Add jsdoc comments to PolicyServiceAbstraction (#6743)

libs/common/src/admin-console/abstractions/policy/policy.service.abstraction.ts

@@ -9,34 +9,87 @@ import { ResetPasswordPolicyOptions } from "../../models/domain/reset-password-p
 import { PolicyResponse } from "../../models/response/policy.response";
 
 export abstract class PolicyService {
+  /**
+   * All {@link Policy} objects for the active user (from sync data).
+   * May include policies that are disabled or otherwise do not apply to the user.
+   * @see {@link get$} or {@link policyAppliesToActiveUser$} if you want to know when a policy applies to a user.
+   */
   policies$: Observable<Policy[]>;
+
+  /**
+   * @returns the first {@link Policy} found that applies to the active user.
+   * A policy "applies" if it is enabled and the user is not exempt (e.g. because they are an Owner).
+   * @param policyType the {@link PolicyType} to search for
+   * @param policyFilter Optional predicate to apply when filtering policies
+   */
   get$: (policyType: PolicyType, policyFilter?: (policy: Policy) => boolean) => Observable<Policy>;
-  masterPasswordPolicyOptions$: (policies?: Policy[]) => Observable<MasterPasswordPolicyOptions>;
+
+  /**
+   * All {@link Policy} objects for the specified user (from sync data).
+   * May include policies that are disabled or otherwise do not apply to the user.
+   * @see {@link policyAppliesToUser} if you want to know when a policy applies to the user.
+   * @deprecated Use {@link policies$} instead
+   */
+  getAll: (type?: PolicyType, userId?: string) => Promise<Policy[]>;
+
+  /**
+   * @returns true if the {@link PolicyType} applies to the current user, otherwise false.
+   * @remarks A policy "applies" if it is enabled and the user is not exempt (e.g. because they are an Owner).
+   */
   policyAppliesToActiveUser$: (
     policyType: PolicyType,
     policyFilter?: (policy: Policy) => boolean
   ) => Observable<boolean>;
 
   /**
-   * @deprecated Do not call this, use the policies$ observable collection
+   * @returns true if the {@link PolicyType} applies to the specified user, otherwise false.
+   * @remarks A policy "applies" if it is enabled and the user is not exempt (e.g. because they are an Owner).
+   * @see {@link policyAppliesToActiveUser$} if you only want to know about the current user.
    */
-  getAll: (type?: PolicyType, userId?: string) => Promise<Policy[]>;
-  evaluateMasterPassword: (
-    passwordStrength: number,
-    newPassword: string,
-    enforcedPolicyOptions?: MasterPasswordPolicyOptions
-  ) => boolean;
-  getResetPasswordPolicyOptions: (
-    policies: Policy[],
-    orgId: string
-  ) => [ResetPasswordPolicyOptions, boolean];
-  mapPolicyFromResponse: (policyResponse: PolicyResponse) => Policy;
-  mapPoliciesFromToken: (policiesResponse: ListResponse<PolicyResponse>) => Policy[];
   policyAppliesToUser: (
     policyType: PolicyType,
     policyFilter?: (policy: Policy) => boolean,
     userId?: string
   ) => Promise<boolean>;
+
+  // Policy specific interfaces
+
+  /**
+   * Combines all Master Password policies that apply to the user.
+   * @returns a set of options which represent the minimum Master Password settings that the user must
+   * comply with in order to comply with **all** Master Password policies.
+   */
+  masterPasswordPolicyOptions$: (policies?: Policy[]) => Observable<MasterPasswordPolicyOptions>;
+
+  /**
+   * Evaluates whether a proposed Master Password complies with all Master Password policies that apply to the user.
+   */
+  evaluateMasterPassword: (
+    passwordStrength: number,
+    newPassword: string,
+    enforcedPolicyOptions?: MasterPasswordPolicyOptions
+  ) => boolean;
+
+  /**
+   * @returns Reset Password policy options for the specified organization and a boolean indicating whether the policy
+   * is enabled
+   */
+  getResetPasswordPolicyOptions: (
+    policies: Policy[],
+    orgId: string
+  ) => [ResetPasswordPolicyOptions, boolean];
+
+  // Helpers
+
+  /**
+   * Instantiates {@link Policy} objects from {@link PolicyResponse} objects.
+   */
+  mapPolicyFromResponse: (policyResponse: PolicyResponse) => Policy;
+
+  /**
+   * Instantiates {@link Policy} objects from {@link ListResponse<PolicyResponse>} objects.
+   */
+  mapPoliciesFromToken: (policiesResponse: ListResponse<PolicyResponse>) => Policy[];
 }
 
 export abstract class InternalPolicyService extends PolicyService {

libs/common/src/admin-console/models/domain/policy.ts

@@ -7,6 +7,11 @@ export class Policy extends Domain {
   organizationId: string;
   type: PolicyType;
   data: any;
+
+  /**
+   * Warning: a user can be exempt from a policy even if the policy is enabled.
+   * @see {@link PolicyService} has methods to tell you whether a policy applies to a user.
+   */
   enabled: boolean;
 
   constructor(obj?: PolicyData) {

libs/common/src/admin-console/services/policy/policy.service.ts

@@ -42,11 +42,6 @@ export class PolicyService implements InternalPolicyServiceAbstraction {
       .subscribe();
   }
 
-  /**
-   * Returns the first policy found that applies to the active user
-   * @param policyType Policy type to search for
-   * @param policyFilter Additional filter to apply to the policy
-   */
   get$(policyType: PolicyType, policyFilter?: (policy: Policy) => boolean): Observable<Policy> {
     return this.policies$.pipe(
       concatMap(async (policies) => {
@@ -64,9 +59,6 @@ export class PolicyService implements InternalPolicyServiceAbstraction {
     );
   }
 
-  /**
-   * @deprecated Do not call this, use the policies$ observable collection
-   */
   async getAll(type?: PolicyType, userId?: string): Promise<Policy[]> {
     let response: Policy[] = [];
     const decryptedPolicies = await this.stateService.getDecryptedPolicies({ userId: userId });