docs(ai): add missing JSDoc descriptions for AI provider tables and t… (#1951)

### Description
Adds missing JSDoc descriptions for exported interfaces, variables, type
aliases, and properties in `firebase-functions/v2/ai` so that all
reference overview tables are populated with descriptions.

### Release notes
relnote: none

Author: shettyvarun268

src/v2/providers/ai/index.ts

@@ -40,6 +40,9 @@ import * as logger from "../../../logger";
 
 export { HttpsError };
 
+/**
+ * Mapping from `FunctionsErrorCode` strings to numeric RPC status codes.
+ */
 export const rpcCodeMap: Record<FunctionsErrorCode, number> = {
   ok: 0,
   cancelled: 1,
@@ -82,32 +85,72 @@ export {
 };
 type MultipleLocationsIf<Allowed extends boolean> = Allowed extends true ? string[] : never;
 
+/**
+ * Options for configuring AI webhook triggers.
+ */
 export interface WebhookOptions<Regional extends boolean = false>
   extends Omit<EventHandlerOptions, "location"> {
+  /**
+   * Region where functions should be deployed. Deployed to `us-central1` by default.
+   */
   location?: string | Expression<string> | MultipleLocationsIf<Regional> | ResetValue;
+  /**
+   * Whether to handle regional webhooks.
+   */
   regionalWebhook?: Regional;
 }
 
+/**
+ * Metadata about the server prompt template used, if applicable.
+ */
 export interface PromptTemplateInfo {
+  /** The name of the server prompt template. */
   templateName?: string;
 }
 
+/**
+ * Authentication state for the caller: `"app_user"`, `"unauthenticated"`, or `"unknown"`.
+ */
 export type AuthType = "app_user" | "unauthenticated" | "unknown";
 
+/**
+ * Event type for `beforeGenerate` triggers.
+ */
 export const beforeGenerateEventType = "google.firebase.ailogic.v1.beforeGenerate";
+/**
+ * Event type for `afterGenerate` triggers.
+ */
 export const afterGenerateEventType = "google.firebase.ailogic.v1.afterGenerate";
 
+/**
+ * Union of all valid AI request payloads across supported Gemini API providers.
+ */
 export type AnyValidAIRequest =
   | GeminiV1BetaGenerateContentRequest
   | VertexV1Beta1GenerateContentRequest;
+/**
+ * Union of all valid AI response payloads across supported Gemini API providers.
+ */
 export type AnyValidAIResponse =
   | GeminiV1BetaGenerateContentResponse
   | VertexV1Beta1GenerateContentResponse;
 
+/**
+ * Identifier for the Gemini Developer API (`geminiV1Beta`).
+ */
 export const geminiV1Beta = "google.ai.generativelanguage.v1beta";
+/**
+ * Identifier for the Agent Platform Gemini API (formerly Vertex AI) (`vertexV1Beta1`).
+ */
 export const vertexV1Beta1 = "google.cloud.aiplatform.v1beta1";
+/**
+ * Supported Gemini API providers: Gemini Developer API or Agent Platform Gemini API (formerly Vertex AI).
+ */
 export type SupportedAPI = typeof geminiV1Beta | typeof vertexV1Beta1;
 
+/**
+ * Generic type resolving to the corresponding AI request type based on the API identifier.
+ */
 export type AIRequest<API> = string extends API
   ? AnyValidAIRequest
   : API extends typeof geminiV1Beta
@@ -116,6 +159,9 @@ export type AIRequest<API> = string extends API
   ? VertexV1Beta1GenerateContentRequest
   : never;
 
+/**
+ * Generic type resolving to the corresponding AI response type based on the API identifier.
+ */
 export type AIResponse<API> = string extends API
   ? AnyValidAIResponse
   : API extends typeof geminiV1Beta
@@ -124,31 +170,56 @@ export type AIResponse<API> = string extends API
   ? VertexV1Beta1GenerateContentResponse
   : never;
 
+/**
+ * Data payload for `beforeGenerateContent` events.
+ */
 export interface BeforeGenerateContentData<API extends string = string> {
+  /** The full model resource path (for example, `projects/{PROJECT_ID}/locations/global/publishers/google/models/gemini-3.5-flash`). */
   model: string;
+  /** Metadata about the server prompt template used, if applicable. */
   template?: PromptTemplateInfo;
+  /** The Gemini API provider: `geminiV1Beta` (Gemini Developer API) or `vertexV1Beta1` (Agent Platform Gemini API (formerly Vertex AI)). */
   api: SupportedAPI;
+  /** The outgoing request payload. */
   request: AIRequest<API>;
 }
 
+/**
+ * Data payload for `afterGenerateContent` events.
+ */
 export interface AfterGenerateContentData<API extends string = string>
   extends BeforeGenerateContentData<API> {
+  /** The model's response payload. */
   response: AIResponse<API>;
 }
 
+/**
+ * Event context and metadata delivered to AI blocking handlers.
+ */
 export interface AIBlockingEvent<T = any> extends CloudEvent<T> {
+  /** Authentication state for the caller: `"app_user"`, `"unauthenticated"`, or `"unknown"`. */
   authType: AuthType;
+  /** The caller's Firebase Authentication UID, if signed in. */
   authId?: string;
+  /** The caller's custom auth claims, if any. */
   authClaims?: any;
+  /** The resource name of the caller or request. */
   resourceName?: string;
+  /** The Firebase App ID that made the request. */
   appId?: string;
+  /** The display name of the calling app, if set. */
   displayName?: string;
+  /** The package name of the calling app (applicable only for apps that target Android platforms). */
   androidPackageName?: string;
+  /** The bundle ID of the calling app (applicable only for apps that target Apple platforms). */
   iosBundleId?: string;
 }
 
 type MaybeAsync<T> = T | Promise<T>;
 
+/**
+ * A function that handles AI blocking events.
+ */
 export type BlockingFunction = HttpsFunction;
 
 /**

src/v2/providers/ai/types/gemini/v1beta/index.ts

@@ -382,9 +382,13 @@ export declare interface GenerateContentCandidate {
  * @public
  */
 export declare interface GenerateContentRequest extends BaseParams {
+  /** Array of conversation turns (Content) that make up the prompt. */
   contents: Content[];
+  /** Optional tools that the model may use to generate content. */
   tools?: Tool[];
+  /** Optional tool configuration. */
   toolConfig?: ToolConfig;
+  /** Optional system instructions for the model. */
   systemInstruction?: string | Part | Content;
   /**
    * This is the name of a `CachedContent` and not the cache object itself.