Adding top-level comment and TOC for functions.handler.

docgen/content-sources/toc.yaml

@@ -116,3 +116,9 @@ toc:
         path: /docs/reference/functions/providers_storage_.objectbuilder.html
       - title: 'ObjectMetadata'
         path: /docs/reference/functions/providers_storage_.objectmetadata.html
+
+  - title: 'functions.handler'
+    path: /docs/reference/functions/handler_builder_.html
+    section:
+      - title: 'HandlerBuilder'
+        path: /docs/reference/functions/handler_builder_.handlerbuilder.html

src/handler-builder.ts

@@ -35,6 +35,15 @@ import * as remoteConfig from './providers/remoteConfig';
 import * as storage from './providers/storage';
 import * as testLab from './providers/testLab';
 
+/**
+ * The `HandlerBuilder` class facilitates the writing of functions by producers
+ * of Firebase Extensions and developers who want to use the gcloud CLI or
+ * Google Cloud Console to deploy their functions.
+ *
+ * **Do not use `HandlerBuilder` when writing normal functions for deployment via
+ * the Firebase CLI.** For normal purposes, use
+ * [`FunctionBuilder`](/docs/reference/functions/function_builder_.functionbuilder).
+ */
 export class HandlerBuilder {
   constructor() {}
 
@@ -52,10 +61,6 @@ export class HandlerBuilder {
         func.__trigger = {};
         return func;
       },
-      /**
-       * Declares a callable method for clients to call using a Firebase SDK.
-       * @param handler A method that takes a data and context and returns a value.
-       */
       onCall: (
         handler: (
           data: any,
@@ -71,40 +76,13 @@ export class HandlerBuilder {
 
   get database() {
     return {
-      /**
-       * Selects a database instance that will trigger the function.
-       * If omitted, will pick the default database for your project.
-       */
       get instance() {
         return {
           get ref() {
             return new database.RefBuilder(apps(), () => null, {});
           },
         };
       },
-
-      /**
-       * Select Firebase Realtime Database Reference to listen to.
-       *
-       * This method behaves very similarly to the method of the same name in the
-       * client and Admin Firebase SDKs. Any change to the Database that affects the
-       * data at or below the provided `path` will fire an event in Cloud Functions.
-       *
-       * There are three important differences between listening to a Realtime
-       * Database event in Cloud Functions and using the Realtime Database in the
-       * client and Admin SDKs:
-       * 1. Cloud Functions allows wildcards in the `path` name. Any `path` component
-       *    in curly brackets (`{}`) is a wildcard that matches all strings. The value
-       *    that matched a certain invocation of a Cloud Function is returned as part
-       *    of the `context.params` object. For example, `ref("messages/{messageId}")`
-       *    matches changes at `/messages/message1` or `/messages/message2`, resulting
-       *    in  `context.params.messageId` being set to `"message1"` or `"message2"`,
-       *    respectively.
-       * 2. Cloud Functions do not fire an event for data that already existed before
-       *    the Cloud Function was deployed.
-       * 3. Cloud Function events have access to more information, including information
-       *    about the user who triggered the Cloud Function.
-       */
       get ref() {
         return new database.RefBuilder(apps(), () => null, {});
       },
@@ -113,10 +91,6 @@ export class HandlerBuilder {
 
   get firestore() {
     return {
-      /**
-       * Listen for events on a Firestore document. A Firestore document contains a set of
-       * key-value pairs and may contain subcollections and nested objects.
-       */
       get document() {
         return new firestore.DocumentBuilder(() => null, {});
       },
@@ -133,10 +107,6 @@ export class HandlerBuilder {
 
   get crashlytics() {
     return {
-      /**
-       * Handle events related to Crashlytics issues. An issue in Crashlytics is an
-       * aggregation of crashes which have a shared root cause.
-       */
       get issue() {
         return new crashlytics.IssueBuilder(() => null, {});
       },
@@ -145,12 +115,6 @@ export class HandlerBuilder {
 
   get remoteConfig() {
     return {
-      /**
-       * Handle all updates (including rollbacks) that affect a Remote Config
-       * project.
-       * @param handler A function that takes the updated Remote Config template
-       * version metadata as an argument.
-       */
       onUpdate: (
         handler: (
           version: remoteConfig.TemplateVersion,
@@ -164,9 +128,6 @@ export class HandlerBuilder {
 
   get analytics() {
     return {
-      /**
-       * Select analytics events to listen to for events.
-       */
       get event() {
         return new analytics.AnalyticsEventBuilder(() => null, {});
       },
@@ -175,18 +136,10 @@ export class HandlerBuilder {
 
   get storage() {
     return {
-      /**
-       * The optional bucket function allows you to choose which buckets' events to handle.
-       * This step can be bypassed by calling object() directly, which will use the default
-       * Cloud Storage for Firebase bucket.
-       */
       get bucket() {
         return new storage.BucketBuilder(() => null, {}).object();
       },
 
-      /**
-       * Handle events related to Cloud Storage objects.
-       */
       get object() {
         return new storage.ObjectBuilder(() => null, {});
       },
@@ -195,15 +148,9 @@ export class HandlerBuilder {
 
   get pubsub() {
     return {
-      /**
-       * Select Cloud Pub/Sub topic to listen to.
-       */
       get topic() {
         return new pubsub.TopicBuilder(() => null, {});
       },
-      /**
-       * Handle periodic events triggered by Cloud Scheduler.
-       */
       get schedule() {
         return new pubsub.ScheduleBuilder(() => null, {});
       },
@@ -212,17 +159,13 @@ export class HandlerBuilder {
 
   get auth() {
     return {
-      /**
-       * Handle events related to Firebase authentication users.
-       */
       get user() {
         return new auth.UserBuilder(() => null, {});
       },
     };
   }
 
   get testLab() {
-    /** Handle events related to Test Lab test matrices. */
     return {
       get testMatrix() {
         return new testLab.TestMatrixBuilder(() => null, {});