Update alerts namespace docs (#1111)

* updating docs

* fixing comments

Author: colerogers

src/v2/providers/alerts/alerts.ts

@@ -4,6 +4,7 @@ import * as options from '../../options';
 
 /**
  * The CloudEvent data emitted by Firebase Alerts.
+ * @typeParam T - the payload type that is expected for this alert.
  */
 export interface FirebaseAlertData<T = any> {
   /** Time that the event has created. */
@@ -16,6 +17,7 @@ export interface FirebaseAlertData<T = any> {
 
 /**
  * A custom CloudEvent for Firebase Alerts (with custom extension attributes).
+ * @typeParam T - the data type for this alert that is wrapped in a `FirebaseAlertData` object.
  */
 export interface AlertEvent<T> extends CloudEvent<FirebaseAlertData<T>> {
   /** The type of the alerts that got triggered. */
@@ -26,7 +28,7 @@ export interface AlertEvent<T> extends CloudEvent<FirebaseAlertData<T>> {
    */
   appId?: string;
 
-  /** Data for an AlertEvent is a FirebaseAlertData with a given payload. */
+  /** Data for an `AlertEvent` is a `FirebaseAlertData` object with a given payload. */
   data: FirebaseAlertData<T>;
 }
 
@@ -50,14 +52,18 @@ export type AlertType =
  * Configuration for Firebase Alert functions.
  */
 export interface FirebaseAlertOptions extends options.EventHandlerOptions {
+  /** Scope the handler to trigger on an alert type. */
   alertType: AlertType;
+  /** Scope the function to trigger on a specific application. */
   appId?: string;
 }
 
 /**
  * Declares a function that can handle Firebase Alerts from CloudEvents.
+ * @typeParam T - The data type of the `FirebaseAlertData` object the function receives.
  * @param alertTypeOrOpts the alert type or Firebase Alert function configuration.
  * @param handler a function that can handle the Firebase Alert inside a CloudEvent.
+ * @returns A function that you can export and deploy.
  */
 export function onAlertPublished<T extends { ['@type']: string } = any>(
   alertTypeOrOpts: AlertType | FirebaseAlertOptions,
@@ -76,8 +82,8 @@ export function onAlertPublished<T extends { ['@type']: string } = any>(
 }
 
 /**
- * @internal
  * Helper function for getting the endpoint annotation used in alert handling functions.
+ * @internal
  */
 export function getEndpointAnnotation(
   opts: options.EventHandlerOptions,
@@ -109,8 +115,8 @@ export function getEndpointAnnotation(
 }
 
 /**
- * @internal
  * Helper function to parse the function opts, alert type, and appId.
+ * @internal
  */
 export function getOptsAndAlertTypeAndApp(
   alertTypeOrOpts: AlertType | FirebaseAlertOptions

src/v2/providers/alerts/appDistribution.ts

@@ -4,7 +4,7 @@ import { FirebaseAlertData, getEndpointAnnotation } from './alerts';
 
 /**
  * The internal payload object for adding a new tester device to app distribution.
- * Payload is wrapped inside a FirebaseAlertData object.
+ * Payload is wrapped inside a `FirebaseAlertData` object.
  */
 export interface NewTesterDevicePayload {
   ['@type']: 'type.googleapis.com/google.events.firebase.firebasealerts.v1.AppDistroNewTesterIosDevicePayload';
@@ -20,6 +20,7 @@ export interface NewTesterDevicePayload {
 
 /**
  * A custom CloudEvent for Firebase Alerts (with custom extension attributes).
+ * @typeParam T - the data type for app distribution alerts that is wrapped in a `FirebaseAlertData` object.
  */
 export interface AppDistributionEvent<T>
   extends CloudEvent<FirebaseAlertData<T>> {
@@ -36,29 +37,53 @@ export const newTesterIosDeviceAlert = 'appDistribution.newTesterIosDevice';
  * Configuration for app distribution functions.
  */
 export interface AppDistributionOptions extends options.EventHandlerOptions {
+  /** Scope the function to trigger on a specific application. */
   appId?: string;
 }
 
 /**
  * Declares a function that can handle adding a new tester iOS device.
+ * @param handler - Event handler which is run every time a new tester iOS device is added.
+ * @returns A function that you can export and deploy.
  */
 export function onNewTesterIosDevicePublished(
   handler: (
     event: AppDistributionEvent<NewTesterDevicePayload>
   ) => any | Promise<any>
 ): CloudFunction<AppDistributionEvent<NewTesterDevicePayload>>;
+
+/**
+ * Declares a function that can handle adding a new tester iOS device.
+ * @param appId - A specific application the handler will trigger on.
+ * @param handler - Event handler which is run every time a new tester iOS device is added.
+ * @returns A function that you can export and deploy.
+ */
 export function onNewTesterIosDevicePublished(
   appId: string,
   handler: (
     event: AppDistributionEvent<NewTesterDevicePayload>
   ) => any | Promise<any>
 ): CloudFunction<AppDistributionEvent<NewTesterDevicePayload>>;
+
+/**
+ * Declares a function that can handle adding a new tester iOS device.
+ * @param opts - Options that can be set on the function.
+ * @param handler - Event handler which is run every time a new tester iOS device is added.
+ * @returns A function that you can export and deploy.
+ */
 export function onNewTesterIosDevicePublished(
   opts: AppDistributionOptions,
   handler: (
     event: AppDistributionEvent<NewTesterDevicePayload>
   ) => any | Promise<any>
 ): CloudFunction<AppDistributionEvent<NewTesterDevicePayload>>;
+
+/**
+ * Declares a function that can handle adding a new tester iOS device.
+ * @param appIdOrOptsOrHandler - A specific application, options, or an event-handling function.
+ * @param handler - Event handler which is run every time a new tester iOS device is added.
+ * @returns A function that you can export and deploy.
+ */
 export function onNewTesterIosDevicePublished(
   appIdOrOptsOrHandler:
     | string
@@ -90,8 +115,8 @@ export function onNewTesterIosDevicePublished(
 }
 
 /**
- * @internal
  * Helper function to parse the function opts and appId.
+ * @internal
  */
 export function getOptsAndApp(
   appIdOrOpts: string | AppDistributionOptions

src/v2/providers/alerts/billing.ts

@@ -4,7 +4,7 @@ import * as options from '../../options';
 
 /**
  * The internal payload object for billing plan updates.
- * Payload is wrapped inside a FirebaseAlertData object.
+ * Payload is wrapped inside a `FirebaseAlertData` object.
  */
 export interface PlanUpdatePayload {
   ['@type']: 'type.googleapis.com/google.events.firebase.firebasealerts.v1.BillingPlanUpdatePayload';
@@ -18,7 +18,7 @@ export interface PlanUpdatePayload {
 
 /**
  * The internal payload object for billing plan automated updates.
- * Payload is wrapped inside a FirebaseAlertData object.
+ * Payload is wrapped inside a `FirebaseAlertData` object.
  */
 export interface PlanAutomatedUpdatePayload {
   ['@type']: 'type.googleapis.com/google.events.firebase.firebasealerts.v1.BillingPlanAutomatedUpdatePayload';
@@ -30,6 +30,7 @@ export interface PlanAutomatedUpdatePayload {
 
 /**
  * A custom CloudEvent for billing Firebase Alerts (with custom extension attributes).
+ * @typeParam T - the data type for billing alerts that is wrapped in a `FirebaseAlertData` object.
  */
 export interface BillingEvent<T> extends CloudEvent<FirebaseAlertData<T>> {
   /** The type of the alerts that got triggered. */
@@ -43,14 +44,30 @@ export const planAutomatedUpdateAlert = 'billing.planAutomatedUpdate';
 
 /**
  * Declares a function that can handle a billing plan update event.
+ * @param handler - Event handler which is run every time a billing plan is updated.
+ * @returns A function that you can export and deploy.
  */
 export function onPlanUpdatePublished(
   handler: (event: BillingEvent<PlanUpdatePayload>) => any | Promise<any>
 ): CloudFunction<BillingEvent<PlanUpdatePayload>>;
+
+/**
+ * Declares a function that can handle a billing plan update event.
+ * @param opts - Options that can be set on the function.
+ * @param handler - Event handler which is run every time a billing plan is updated.
+ * @returns A function that you can export and deploy.
+ */
 export function onPlanUpdatePublished(
   opts: options.EventHandlerOptions,
   handler: (event: BillingEvent<PlanUpdatePayload>) => any | Promise<any>
 ): CloudFunction<BillingEvent<PlanUpdatePayload>>;
+
+/**
+ * Declares a function that can handle a billing plan update event.
+ * @param optsOrHandler - Options or an event-handling function.
+ * @param handler - Event handler which is run every time a billing plan is updated.
+ * @returns A function that you can export and deploy.
+ */
 export function onPlanUpdatePublished(
   optsOrHandler:
     | options.EventHandlerOptions
@@ -66,18 +83,34 @@ export function onPlanUpdatePublished(
 
 /**
  * Declares a function that can handle an automated billing plan update event.
+ * @param handler - Event handler which is run every time an automated billing plan update occurs.
+ * @returns A function that you can export and deploy.
  */
 export function onPlanAutomatedUpdatePublished(
   handler: (
     event: BillingEvent<PlanAutomatedUpdatePayload>
   ) => any | Promise<any>
 ): CloudFunction<BillingEvent<PlanAutomatedUpdatePayload>>;
+
+/**
+ * Declares a function that can handle an automated billing plan update event.
+ * @param opts - Options that can be set on the function.
+ * @param handler - Event handler which is run every time an automated billing plan update occurs.
+ * @returns A function that you can export and deploy.
+ */
 export function onPlanAutomatedUpdatePublished(
   opts: options.EventHandlerOptions,
   handler: (
     event: BillingEvent<PlanAutomatedUpdatePayload>
   ) => any | Promise<any>
 ): CloudFunction<BillingEvent<PlanAutomatedUpdatePayload>>;
+
+/**
+ * Declares a function that can handle an automated billing plan update event.
+ * @param optsOrHandler - Options or an event-handling function.
+ * @param handler - Event handler which is run every time an automated billing plan update occurs.
+ * @returns A function that you can export and deploy.
+ */
 export function onPlanAutomatedUpdatePublished(
   optsOrHandler:
     | options.EventHandlerOptions