Refreshing 1st gen reference and making some style and format tweaks. (#1490)

Author: egilmorez

src/common/providers/identity.ts

@@ -63,18 +63,19 @@ const EVENT_MAPPING: Record<string, string> = {
 };
 
 /**
- * The UserRecord passed to Cloud Functions is the same UserRecord that is returned by the Firebase Admin
- * SDK.
+ * The `UserRecord` passed to Cloud Functions is the same
+ * {@link https://firebase.google.com/docs/reference/admin/node/firebase-admin.auth.userrecord | UserRecord}
+ * that is returned by the Firebase Admin SDK.
  */
 export type UserRecord = auth.UserRecord;
 
 /**
- * UserInfo that is part of the UserRecord
+ * `UserInfo` that is part of the `UserRecord`.
  */
 export type UserInfo = auth.UserInfo;
 
 /**
- * Helper class to create the user metadata in a UserRecord object
+ * Helper class to create the user metadata in a `UserRecord` object.
  */
 export class UserRecordMetadata implements auth.UserMetadata {
   constructor(public creationTime: string, public lastSignInTime: string) {}
@@ -89,9 +90,9 @@ export class UserRecordMetadata implements auth.UserMetadata {
 }
 
 /**
- * Helper function that creates a UserRecord Class from data sent over the wire.
+ * Helper function that creates a `UserRecord` class from data sent over the wire.
  * @param wireData data sent over the wire
- * @returns an instance of UserRecord with correct toJSON functions
+ * @returns an instance of `UserRecord` with correct toJSON functions
  */
 export function userRecordConstructor(wireData: Record<string, unknown>): UserRecord {
   // Falsey values from the wire format proto get lost when converted to JSON, this adds them back.
@@ -157,7 +158,7 @@ export function userRecordConstructor(wireData: Record<string, unknown>): UserRe
 }
 
 /**
- * User info that is part of the AuthUserRecord
+ * User info that is part of the `AuthUserRecord`.
  */
 export interface AuthUserInfo {
   /**
@@ -237,7 +238,7 @@ export interface AuthMultiFactorSettings {
 }
 
 /**
- * The UserRecord passed to auth blocking Cloud Functions from the identity platform.
+ * The `UserRecord` passed to auth blocking functions from the identity platform.
  */
 export interface AuthUserRecord {
   /**
@@ -334,7 +335,7 @@ export interface AuthEventContext extends EventContext {
   credential?: Credential;
 }
 
-/** Defines the auth event for v2 blocking events */
+/** Defines the auth event for 2nd gen blocking events */
 export interface AuthBlockingEvent extends AuthEventContext {
   data: AuthUserRecord;
 }
@@ -344,7 +345,7 @@ export interface AuthBlockingEvent extends AuthEventContext {
  */
 export type RecaptchaActionOptions = "ALLOW" | "BLOCK";
 
-/** The handler response type for beforeCreate blocking events */
+/** The handler response type for `beforeCreate` blocking events */
 export interface BeforeCreateResponse {
   displayName?: string;
   disabled?: boolean;
@@ -354,7 +355,7 @@ export interface BeforeCreateResponse {
   recaptchaActionOverride?: RecaptchaActionOptions;
 }
 
-/** The handler response type for beforeSignIn blocking events */
+/** The handler response type for `beforeSignIn` blocking events */
 export interface BeforeSignInResponse extends BeforeCreateResponse {
   sessionClaims?: object;
 }
@@ -472,7 +473,7 @@ type HandlerV2 = (
   | Promise<void>;
 
 /**
- * Checks for a valid identity platform web request, otherwise throws an HttpsError
+ * Checks for a valid identity platform web request, otherwise throws an HttpsError.
  * @internal
  */
 export function isValidRequest(req: express.Request): boolean {
@@ -508,7 +509,7 @@ function unsafeDecodeAuthBlockingToken(token: string): DecodedPayload {
 }
 
 /**
- * Helper function to parse the decoded metadata object into a UserMetaData object
+ * Helper function to parse the decoded metadata object into a `UserMetaData` object
  * @internal
  */
 export function parseMetadata(metadata: DecodedPayloadUserRecordMetadata): AuthUserMetadata {
@@ -525,7 +526,7 @@ export function parseMetadata(metadata: DecodedPayloadUserRecordMetadata): AuthU
 }
 
 /**
- * Helper function to parse the decoded user info array into an AuthUserInfo array
+ * Helper function to parse the decoded user info array into an `AuthUserInfo` array.
  * @internal
  */
 export function parseProviderData(
@@ -546,7 +547,7 @@ export function parseProviderData(
 }
 
 /**
- * Helper function to parse the date into a UTC string
+ * Helper function to parse the date into a UTC string.
  * @internal
  */
 export function parseDate(tokensValidAfterTime?: number): string | null {
@@ -639,7 +640,7 @@ export function parseAuthUserRecord(
   };
 }
 
-/** Helper to get the AdditionalUserInfo from the decoded jwt */
+/** Helper to get the `AdditionalUserInfo` from the decoded JWT */
 function parseAdditionalUserInfo(decodedJWT: DecodedPayload): AdditionalUserInfo {
   let profile;
   let username;
@@ -697,7 +698,7 @@ export function generateResponsePayload(
   return result;
 }
 
-/** Helper to get the Credential from the decoded jwt */
+/** Helper to get the Credential from the decoded JWT */
 function parseAuthCredential(decodedJWT: DecodedPayload, time: number): Credential {
   if (
     !decodedJWT.sign_in_attributes &&

src/common/providers/tasks.ts

@@ -98,8 +98,8 @@ export interface TaskContext {
   /**
    * The "short" name of the task, or, if no name was specified at creation, a unique
    * system-generated id.
-   * This is the my-task-id value in the complete task name, ie, task_name =
-   * projects/my-project-id/locations/my-location/queues/my-queue-id/tasks/my-task-id.
+   * This is the "my-task-id" value in the complete task name, such as "task_name =
+   * projects/my-project-id/locations/my-location/queues/my-queue-id/tasks/my-task-id."
    * Populated via the `X-CloudTasks-TaskName` header.
    */
   id: string;

src/v1/function-configuration.ts

@@ -252,7 +252,8 @@ export interface RuntimeOptions {
    *
    * @remarks
    * Set this to true to enable the App Check replay protection feature by consuming the App Check token on callable
-   * request. Tokens that are found to be already consumed will have request.app.alreadyConsumed property set true.
+   * request. Tokens that are found to be already consumed will have the `request.app.alreadyConsumed` property set
+   * to true.
    *
    *
    * Tokens are only considered to be consumed if it is sent to the App Check service by setting this option to true.
@@ -263,10 +264,10 @@ export interface RuntimeOptions {
    * performance and can potentially deplete your attestation providers' quotas faster. Use this feature only for
    * protecting low volume, security critical, or expensive operations.
    *
-   * This option does not affect the enforceAppCheck option. Setting the latter to true will cause the callable function
-   * to automatically respond with a 401 Unauthorized status code when request includes an invalid App Check token.
-   * When request includes valid but consumed App Check tokens, requests will not be automatically rejected. Instead,
-   * the request.app.alreadyConsumed property will be set to true and pass the execution to the handler code for making
+   * This option does not affect the `enforceAppCheck` option. Setting the latter to true will cause the callable function
+   * to automatically respond with a 401 Unauthorized status code when the request includes an invalid App Check token.
+   * When the request includes valid but consumed App Check tokens, requests will not be automatically rejected. Instead,
+   * the `request.app.alreadyConsumed` property will be set to true and pass the execution to the handler code for making
    * further decisions, such as requiring additional security checks or rejecting the request.
    */
   consumeAppCheckToken?: boolean;