chore: docblock improvements

packages/entity/src/EnforcingEntityCreator.ts

@@ -6,7 +6,7 @@ import { ReadonlyEntity } from './ReadonlyEntity';
 import { ViewerContext } from './ViewerContext';
 
 /**
- * Enforcing entity creator. All updates
+ * Enforcing entity creator. All creates
  * through this creator will throw if authorization is not successful.
  */
 export class EnforcingEntityCreator<

packages/entity/src/Entity.ts

@@ -32,6 +32,12 @@ import { ViewerContext } from './ViewerContext';
  *
  * All concrete entity implementations should extend this class and provide their
  * own EntityCompanionDefinition.
+ *
+ * Generic type parameters:
+ * TFields - the shape of the underlying data for this entity, typically corresponding to a database table schema. The mapping from TFields to the actual database schema is defined in the EntityCompanionDefinition for this entity.
+ * TIDField - the key of the ID field in TFields, which must be non-nullable and is used to uniquely identify individual entities
+ * TViewerContext - the type of ViewerContext that can be used with this entity
+ * TSelectedFields - the keys of fields in TFields that belong to this entity; used when there are multiple entities backed by the same underlying table with different field subsets
  */
 export abstract class Entity<
   TFields extends Record<string, any>,

packages/entity/src/EntityPrivacyPolicy.ts

@@ -123,27 +123,42 @@ export abstract class EntityPrivacyPolicy<
   TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>,
   TSelectedFields extends keyof TFields = keyof TFields,
 > {
+  /**
+   * List of rules to evaluate for create authorization.
+   */
   protected readonly createRules: readonly PrivacyPolicyRule<
     TFields,
     TIDField,
     TViewerContext,
     TEntity,
     TSelectedFields
   >[] = [];
+
+  /**
+   * List of rules to evaluate for read authorization.
+   */
   protected readonly readRules: readonly PrivacyPolicyRule<
     TFields,
     TIDField,
     TViewerContext,
     TEntity,
     TSelectedFields
   >[] = [];
+
+  /**
+   * List of rules to evaluate for update authorization.
+   */
   protected readonly updateRules: readonly PrivacyPolicyRule<
     TFields,
     TIDField,
     TViewerContext,
     TEntity,
     TSelectedFields
   >[] = [];
+
+  /**
+   * List of rules to evaluate for delete authorization.
+   */
   protected readonly deleteRules: readonly PrivacyPolicyRule<
     TFields,
     TIDField,
@@ -156,6 +171,9 @@ export abstract class EntityPrivacyPolicy<
    * Get the privacy policy evaluation mode and deny handler for this policy.
    * Defaults to normal enforcing policy.
    *
+   * DRY_RUN mode is useful for testing and logging the effects of a policy without actually enforcing it, such as when
+   * first rolling out a new policy. Entities that fail the policy will be allowed so caution should be take when using.
+   *
    * @remarks
    *
    * Override to enable dry run evaluation of the policy.
@@ -204,7 +222,9 @@ export abstract class EntityPrivacyPolicy<
    * Authorize an entity against read policy.
    * @param viewerContext - viewer context of user reading the entity
    * @param queryContext - query context in which to perform the read authorization
+   * @param evaluationContext - context about the reason for this privacy policy evaluation
    * @param entity - entity to authorize
+   * @param metricsAdapter - adapter for logging metrics about this authorization
    * @returns entity if authorized
    * @throws EntityNotAuthorizedError when not authorized
    */
@@ -236,7 +256,9 @@ export abstract class EntityPrivacyPolicy<
    * Authorize an entity against update policy.
    * @param viewerContext - viewer context of user updating the entity
    * @param queryContext - query context in which to perform the update authorization
+   * @param evaluationContext - context about the reason for this privacy policy evaluation
    * @param entity - entity to authorize
+   * @param metricsAdapter - adapter for logging metrics about this authorization
    * @returns entity if authorized
    * @throws EntityNotAuthorizedError when not authorized
    */
@@ -268,7 +290,9 @@ export abstract class EntityPrivacyPolicy<
    * Authorize an entity against deletion policy.
    * @param viewerContext - viewer context of user deleting the entity
    * @param queryContext - query context in which to perform the delete authorization
+   * @param evaluationContext - context about the reason for this privacy policy evaluation
    * @param entity - entity to authorize
+   * @param metricsAdapter - adapter for logging metrics about this authorization
    * @returns entity if authorized
    * @throws EntityNotAuthorizedError when not authorized
    */

packages/entity/src/internal/EntityLoadInterfaces.ts

@@ -3,6 +3,8 @@ import { ISerializable, SerializableKeyMap } from '../utils/collections/Serializ
 
 /**
  * Load method type identifier of a load key. Used for keying data loaders and identification in metrics.
+ *
+ * @internal
  */
 export enum EntityLoadMethodType {
   /**