Adding some format and style edits for common or top-level reference pages. (#1438)

Author: egilmorez

src/common/change.ts

@@ -21,7 +21,7 @@
 // SOFTWARE.
 
 /**
- * `ChangeJson` is the JSON format used to construct a Change object.
+ * `ChangeJson` is the JSON format used to construct a `Change` object.
  */
 export interface ChangeJson {
   /**
@@ -64,24 +64,24 @@ export function applyFieldMask(sparseBefore: any, after: any, fieldMask: string)
 }
 
 /**
- * The Functions interface for events that change state, such as
- * Realtime Database or Cloud Firestore `onWrite` and `onUpdate`.
+ * The Cloud Functions interface for events that change state, such as
+ * Realtime Database or Cloud Firestore `onWrite` and `onUpdate` events.
  *
  * For more information about the format used to construct `Change` objects, see
  * {@link ChangeJson} below.
  *
  */
 export class Change<T> {
   /**
-   * Factory method for creating a Change from a `before` object and an `after`
+   * Factory method for creating a `Change` from a `before` object and an `after`
    * object.
    */
   static fromObjects<T>(before: T, after: T) {
     return new Change(before, after);
   }
 
   /**
-   * Factory method for creating a Change from a JSON and an optional customizer
+   * Factory method for creating a `Change` from JSON and an optional customizer
    * function to be applied to both the `before` and the `after` fields.
    */
   static fromJSON<T>(json: ChangeJson, customizer: (x: any) => T = (x) => x as T): Change<T> {

src/v2/core.ts

@@ -21,7 +21,7 @@
 // SOFTWARE.
 
 /**
- * Core functionality of the Firebase Functions v2 SDK.
+ * Core functionality of the Cloud Functions for Firebase 2nd gen SDK.
  * @packageDocumentation
  */
 
@@ -64,8 +64,8 @@ export interface TriggerAnnotation {
 }
 
 /**
- * A CloudEventBase is the base of a cross-platform format for encoding a serverless event.
- * More information can be found in https://github.com/cloudevents/spec
+ * A `CloudEventBase` is the base of a cross-platform format for encoding a serverless event.
+ * For more information, see https://github.com/cloudevents/spec.
  * @typeParam T - The type of the event data.
  * @beta
  */
@@ -76,10 +76,10 @@ export interface CloudEvent<T> {
   /** A globally unique ID for this event. */
   id: string;
 
-  /** The resource which published this event. */
+  /** The resource that published this event. */
   source: string;
 
-  /** The resource, provided by source, that this event relates to */
+  /** The resource, provided by source, that this event relates to. */
   subject?: string;
 
   /** The type of event that this represents. */
@@ -107,10 +107,10 @@ export interface CloudFunction<EventType extends CloudEvent<unknown>> {
   __endpoint: ManifestEndpoint;
 
   /**
-   * The callback passed to the CloudFunction constructor.
-   * Use run to test a CloudFunction
+   * The callback passed to the `CloudFunction` constructor.
+   * Use `run` to test a function.
    * @param event - The parsed event to handle.
-   * @returns Any return value. Google Cloud Functions awaits any promise
+   * @returns Any return value. Cloud Functions awaits any promise
    *          before shutting down your function. Resolved return values
    *          are only used for unit testing purposes.
    * @beta

src/v2/index.ts

@@ -21,10 +21,10 @@
 // SOFTWARE.
 
 /**
- * The V2 API for Cloud Functions for Firebase.
- * This SDK also supports deep imports. For example, the namespace
- * 'pubsub' is available at 'firebase-functions/v2' or is directly importable
- * from 'firebase-functions/v2/pubsub'.
+ * The 2nd gen API for Cloud Functions for Firebase.
+ * This SDK supports deep imports. For example, the namespace
+ * `pubsub` is available at `firebase-functions/v2` or is directly importable
+ * from `firebase-functions/v2/pubsub`.
  * @packageDocumentation
  */
 

src/v2/options.ts

@@ -42,7 +42,7 @@ import * as logger from "../logger";
 export { RESET_VALUE } from "../common/options";
 
 /**
- * List of all regions supported by Cloud Functions v2
+ * List of all regions supported by Cloud Functions (2nd gen).
  */
 export type SupportedRegion =
   | "asia-east1"
@@ -98,18 +98,18 @@ const MemoryOptionToMB: Record<MemoryOption, number> = {
 };
 
 /**
- * List of available options for VpcConnectorEgressSettings.
+ * List of available options for `VpcConnectorEgressSettings`.
  */
 export type VpcEgressSetting = "PRIVATE_RANGES_ONLY" | "ALL_TRAFFIC";
 
 /**
- * List of available options for IngressSettings.
+ * List of available options for `IngressSettings`.
  */
 export type IngressSetting = "ALLOW_ALL" | "ALLOW_INTERNAL_ONLY" | "ALLOW_INTERNAL_AND_GCLB";
 
 /**
- * GlobalOptions are options that can be set across an entire project.
- * These options are common to HTTPS and Event handling functions.
+ * `GlobalOptions` are options that can be set across an entire project.
+ * These options are common to HTTPS and event handling functions.
  */
 export interface GlobalOptions {
   /**
@@ -132,33 +132,33 @@ export interface GlobalOptions {
    * HTTPS functions can specify a higher timeout.
    *
    * @remarks
-   * The minimum timeout for a gen 2 function is 1s. The maximum timeout for a
+   * The minimum timeout for a 2nd gen function is 1s. The maximum timeout for a
    * function depends on the type of function: Event handling functions have a
    * maximum timeout of 540s (9 minutes). HTTPS and callable functions have a
    * maximum timeout of 36,00s (1 hour). Task queue functions have a maximum
-   * timeout of 1,800s (30 minutes)
+   * timeout of 1,800s (30 minutes).
    */
   timeoutSeconds?: number | Expression<number> | ResetValue;
 
   /**
-   * Min number of actual instances to be running at a given time.
+   * Minimum number of actual instances to be running at a given time.
    *
    * @remarks
-   * Instances will be billed for memory allocation and 10% of CPU allocation
+   * Instances are billed for memory allocation and 10% of CPU allocation
    * while idle.
    */
   minInstances?: number | Expression<number> | ResetValue;
 
   /**
-   * Max number of instances to be running in parallel.
+   * Max number of instances that can be running in parallel.
    */
   maxInstances?: number | Expression<number> | ResetValue;
 
   /**
    * Number of requests a function can serve at once.
    *
    * @remarks
-   * Can only be applied to functions running on Cloud Functions v2.
+   * Can be applied only to functions running on Cloud Functions (2nd gen)).
    * A value of null restores the default concurrency (80 when CPU >= 1, 1 otherwise).
    * Concurrency cannot be set to any value other than 1 if `cpu` is less than 1.
    * The maximum value for concurrency is 1,000.
@@ -171,14 +171,14 @@ export interface GlobalOptions {
    * @remarks
    * Defaults to 1 for functions with <= 2GB RAM and increases for larger memory sizes.
    * This is different from the defaults when using the gcloud utility and is different from
-   * the fixed amount assigned in Google Cloud Functions generation 1.
-   * To revert to the CPU amounts used in gcloud or in Cloud Functions generation 1, set this
+   * the fixed amount assigned in Cloud Functions (1st gen).
+   * To revert to the CPU amounts used in gcloud or in Cloud Functions (1st gen), set this
    * to the value "gcf_gen1"
    */
   cpu?: number | "gcf_gen1";
 
   /**
-   * Connect cloud function to specified VPC connector.
+   * Connect a function to a specified VPC connector.
    */
   vpcConnector?: string | Expression<string> | ResetValue;
 
@@ -198,7 +198,7 @@ export interface GlobalOptions {
   ingressSettings?: IngressSetting | ResetValue;
 
   /**
-   * Invoker to set access control on https functions.
+   * Invoker to set access control on HTTPS functions.
    */
   invoker?: "public" | "private" | string | string[];
 
@@ -213,21 +213,21 @@ export interface GlobalOptions {
   secrets?: (string | SecretParam)[];
 
   /**
-   * Determines whether Firebase AppCheck is enforced. Defaults to false.
+   * Determines whether Firebase App Check is enforced. Defaults to false.
    *
    * @remarks
    * When true, requests with invalid tokens autorespond with a 401
    * (Unauthorized) error.
-   * When false, requests with invalid tokens set event.app to undefined.
+   * When false, requests with invalid tokens set `event.app` to `undefined`.
    */
   enforceAppCheck?: boolean;
 
   /**
    * Controls whether function configuration modified outside of function source is preserved. Defaults to false.
    *
    * @remarks
-   * When setting configuration available in the underlying platform that is not yet available in the Firebase Functions
-   * SDK, we highly recommend setting `preserveExternalChanges` to `true`. Otherwise, when the Firebase Functions SDK releases
+   * When setting configuration available in an underlying platform that is not yet available in the Firebase SDK
+   * for Cloud Functions, we recommend setting `preserveExternalChanges` to `true`. Otherwise, when Google releases
    * a new version of the SDK with support for the missing configuration, your function's manually configured setting
    * may inadvertently be wiped out.
    */
@@ -237,7 +237,7 @@ export interface GlobalOptions {
 let globalOptions: GlobalOptions | undefined;
 
 /**
- * Sets default options for all functions written using the v2 SDK.
+ * Sets default options for all functions written using the 2nd gen SDK.
  * @param options Options to set as default
  */
 export function setGlobalOptions(options: GlobalOptions) {
@@ -257,12 +257,16 @@ export function getGlobalOptions(): GlobalOptions {
 }
 
 /**
- * Additional fields that can be set on any event-handling Cloud Function.
+ * Additional fields that can be set on any event-handling function.
  */
 export interface EventHandlerOptions extends Omit<GlobalOptions, "enforceAppCheck"> {
+   /** Type of the event. Valid values are TODO */
   eventType?: string;
 
+  /** TODO */
   eventFilters?: Record<string, string | Expression<string>>;
+
+  /** TODO */
   eventFilterPathPatterns?: Record<string, string | Expression<string>>;
 
   /** Whether failed executions should be delivered again. */