Improve documentation for task queue functions (#1112)

* Improve documentation for task queue functions

* PR feedback

Author: inlined

src/common/providers/tasks.ts

@@ -61,13 +61,20 @@ export interface RetryConfig {
 
 /** How congestion control should be applied to the function. */
 export interface RateLimits {
-  // If left unspecified, wild default to 1000
+  /**
+   * The maximum number of requests that can be outstanding at a time.
+   * If left unspecified, will default to 1000.
+   */
   maxConcurrentDispatches?: number;
 
-  // If left unspecified, will default to 500
+  /**
+   * The maximum number of requests that can be invoked per second.
+   * If left unspecified, will default to 500.
+   */
   maxDispatchesPerSecond?: number;
 }
 
+/** Metadata about the authorization used to invoke a function. */
 export interface AuthData {
   uid: string;
   token: firebase.auth.DecodedIdToken;

src/providers/tasks.ts

@@ -38,51 +38,67 @@ import {
 import { DeploymentOptions } from '../function-configuration';
 import { ManifestEndpoint, ManifestRequiredAPI } from '../runtime/manifest';
 
-export {
-  /** @hidden */
-  RetryConfig as RetryPolicy,
-  /** @hidden */
-  RateLimits,
-  /** @hidden */
-  TaskContext,
-};
+export { RetryConfig, RateLimits, TaskContext };
 
 /**
- * Configurations for Task Queue Functions.
- * @hidden
+ * Options for configuring the task queue to listen to.
  */
 export interface TaskQueueOptions {
+  /** How a task should be retried in the event of a non-2xx return. */
   retryConfig?: RetryConfig;
+  /** How congestion control should be applied to the function. */
   rateLimits?: RateLimits;
 
   /**
    * Who can enqueue tasks for this function.
    * If left unspecified, only service accounts which have
-   * roles/cloudtasks.enqueuer and roles/cloudfunctions.invoker
+   * `roles/cloudtasks.enqueuer` and `roles/cloudfunctions.invoker`
    * will have permissions.
    */
   invoker?: 'private' | string | string[];
 }
 
-/** @hidden */
+/**
+ * A handler for tasks.
+ */
 export interface TaskQueueFunction {
   (req: Request, res: express.Response): Promise<void>;
 
+  /** @alpha */
   __trigger: unknown;
+
+  /** @alpha */
   __endpoint: ManifestEndpoint;
+
+  /** @alpha */
   __requiredAPIs?: ManifestRequiredAPI[];
 
+  /**
+   * The callback passed to the `TaskQueueFunction` constructor.
+   * @param data - The body enqueued into a task queue.
+   * @param context - The request context of the enqueued task
+   * @returns Any return value. Google Cloud Functions will await any promise
+   *          before shutting down your function. Resolved return values
+   *          are only used for unit testing purposes.
+   */
   run(data: any, context: TaskContext): void | Promise<void>;
 }
 
-/** @hidden */
+/**
+ * Builder for creating a `TaskQueueFunction`.
+ */
 export class TaskQueueBuilder {
   /** @internal */
   constructor(
     private readonly tqOpts?: TaskQueueOptions,
     private readonly depOpts?: DeploymentOptions
   ) {}
 
+  /**
+   * Creates a handler for tasks sent to a Google Cloud Tasks queue.
+   * @param handler - A callback to handle task requests.
+   * @returns A Cloud Function you can export and deploy.
+   */
   onDispatch(
     handler: (data: any, context: TaskContext) => void | Promise<void>
   ): TaskQueueFunction {
@@ -137,8 +153,8 @@ export class TaskQueueBuilder {
 
 /**
  * Declares a function that can handle tasks enqueued using the Firebase Admin SDK.
- * @param options Configuration for the Task Queue that feeds into this function.
- * @hidden
+ * @param options - Configuration for the Task Queue that feeds into this function.
+ *        Omitting options will configure a Task Queue with default settings.
  */
 export function taskQueue(options?: TaskQueueOptions): TaskQueueBuilder {
   return new TaskQueueBuilder(options);

src/v2/providers/tasks.ts

@@ -35,7 +35,7 @@ import {
 import * as options from '../options';
 import { HttpsFunction } from './https';
 
-export { AuthData, RateLimits, Request, RetryConfig as RetryPolicy };
+export { AuthData, RateLimits, Request, RetryConfig };
 
 export interface TaskQueueOptions extends options.EventHandlerOptions {
   /** How a task should be retried in the event of a non-2xx return. */
@@ -47,7 +47,7 @@ export interface TaskQueueOptions extends options.EventHandlerOptions {
   /**
    * Who can enqueue tasks for this function.
    * If left unspecified, only service accounts which have
-   * roles/cloudtasks.enqueuer and roles/cloudfunctions.invoker
+   * `roles/cloudtasks.enqueuer` and `roles/cloudfunctions.invoker`
    * will have permissions.
    */
   invoker?: 'private' | string | string[];
@@ -146,15 +146,38 @@ export interface TaskQueueOptions extends options.EventHandlerOptions {
   retry?: boolean;
 }
 
+/**
+ * A handler for tasks.
+ * @typeParam T - The task data interface. Task data is unmarshaled from JSON.
+ */
 export interface TaskQueueFunction<T = any> extends HttpsFunction {
-  run(data: Request<T>): void | Promise<void>;
+  /**
+   * The callback passed to the `TaskQueueFunction` constructor.
+   * @param request - A TaskRequest containing data and auth information.
+   * @returns Any return value. Google Cloud Functions will await any promise
+   *          before shutting down your function. Resolved return values
+   *          are only used for unit testing purposes.
+   */
+  run(request: Request<T>): void | Promise<void>;
 }
 
-/** Handle a request sent to a Cloud Tasks queue. */
+/**
+ * Creates a handler for tasks sent to a Google Cloud Tasks queue.
+ * @param handler - A callback to handle task requests.
+ * @typeParam Args - The interface for the request's `data` field.
+ * @returns A Cloud Function you can export and deploy.
+ */
 export function onTaskDispatched<Args = any>(
   handler: (request: Request<Args>) => void | Promise<void>
 ): TaskQueueFunction<Args>;
-/** Handle a request sent to a Cloud Tasks queue. */
+
+/**
+ * Creates a handler for tasks sent to a Google Cloud Tasks queue.
+ * @param options - Configuration for the task queue or Cloud Function.
+ * @param handler - A callback to handle task requests.
+ * @typeParam Args - The interface for the request's `data` field.
+ * @returns A Cloud Function you can export and deploy.
+ */
 export function onTaskDispatched<Args = any>(
   options: TaskQueueOptions,
   handler: (request: Request<Args>) => void | Promise<void>