Update docs for root namespace (#1101)

* Attempted fix; not sure why some things aren't showing up

* Update docs; pull params namespace

* Don't try to use bulleted list in field comments; they don't render

* Yank @beta tags; run formatter

* PR feedback

Author: inlined

src/v2/core.ts

@@ -56,6 +56,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
+ * @typeParam T - The type of the event data.
+ * @beta
  */
 export interface CloudEvent<T> {
   /** Version of the CloudEvents spec for this event. */
@@ -80,12 +82,28 @@ export interface CloudEvent<T> {
   data: T;
 }
 
-/** A handler for CloudEvents. */
+/**
+ * A handler for CloudEvents.
+ * @typeParam EventType - The kind of event this function handles.
+ *            Always a subclass of CloudEvent<>
+ * @beta
+ */
 export interface CloudFunction<EventType extends CloudEvent<unknown>> {
   (raw: CloudEvent<unknown>): any | Promise<any>;
 
+  /** @alpha */
   __trigger?: unknown;
+  /** @alpha */
   __endpoint: ManifestEndpoint;
 
+  /**
+   * The callback passed to the CloudFunction constructor.
+   * Use run to test a CloudFunction
+   * @param event - The parsed event to handle.
+   * @returns Any return value. Google Cloud Functions awaits any promise
+   *          before shutting down your function. Resolved return values
+   *          are only used for unit testing purposes.
+   * @beta
+   */
   run(event: EventType): any | Promise<any>;
 }

src/v2/index.ts

@@ -21,7 +21,6 @@
 // SOFTWARE.
 
 import * as logger from '../logger';
-import * as params from './params';
 import * as alerts from './providers/alerts';
 import * as eventarc from './providers/eventarc';
 import * as https from './providers/https';
@@ -30,18 +29,16 @@ import * as pubsub from './providers/pubsub';
 import * as storage from './providers/storage';
 import * as tasks from './providers/tasks';
 
-export {
-  alerts,
-  https,
-  identity,
-  pubsub,
-  storage,
-  logger,
-  params,
-  tasks,
-  eventarc,
-};
+export { alerts, https, identity, pubsub, storage, logger, tasks, eventarc };
 
-export { setGlobalOptions, GlobalOptions } from './options';
+export {
+  setGlobalOptions,
+  GlobalOptions,
+  SupportedRegion,
+  MemoryOption,
+  VpcEgressSetting,
+  IngressSetting,
+  EventHandlerOptions,
+} from './options';
 
 export { CloudFunction, CloudEvent } from './core';

src/v2/options.ts

@@ -36,55 +36,28 @@ import { HttpsOptions } from './providers/https';
 /**
  * List of all regions supported by Cloud Functions v2
  */
-export const SUPPORTED_REGIONS = [
-  'asia-northeast1',
-  'europe-north1',
-  'europe-west1',
-  'europe-west4',
-  'us-central1',
-  'us-east1',
-  'us-west1',
-] as const;
-
-/**
- * A region known to be supported by CloudFunctions v2
- */
-export type SupportedRegion = typeof SUPPORTED_REGIONS[number];
-
-/**
- * Cloud Functions v2 min timeout value.
- */
-export const MIN_TIMEOUT_SECONDS = 1;
-
-/**
- * Cloud Functions v2 max timeout value for event handlers.
- */
-export const MAX_EVENT_TIMEOUT_SECONDS = 540;
-
-/**
- * Cloud Functions v2 max timeout for HTTPS functions.
- */
-export const MAX_HTTPS_TIMEOUT_SECONDS = 36_000;
-
-/**
- * Maximum number of requests to serve on a single instance.
- */
-export const MAX_CONCURRENCY = 1_000;
+export type SupportedRegion =
+  | 'asia-northeast1'
+  | 'europe-north1'
+  | 'europe-west1'
+  | 'europe-west4'
+  | 'us-central1'
+  | 'us-east1'
+  | 'us-west1';
 
 /**
  * List of available memory options supported by Cloud Functions.
  */
-export const SUPPORTED_MEMORY_OPTIONS = [
-  '128MiB',
-  '256MiB',
-  '512MiB',
-  '1GiB',
-  '2GiB',
-  '4GiB',
-  '8GiB',
-  '16GiB',
-  '32GiB',
-] as const;
+export type MemoryOption =
+  | '128MiB'
+  | '256MiB'
+  | '512MiB'
+  | '1GiB'
+  | '2GiB'
+  | '4GiB'
+  | '8GiB'
+  | '16GiB'
+  | '32GiB';
 
 const MemoryOptionToMB: Record<MemoryOption, number> = {
   '128MiB': 128,
@@ -98,34 +71,18 @@ const MemoryOptionToMB: Record<MemoryOption, number> = {
   '32GiB': 32768,
 };
 
-/**
- * A supported memory option.
- */
-export type MemoryOption = typeof SUPPORTED_MEMORY_OPTIONS[number];
-
 /**
  * List of available options for VpcConnectorEgressSettings.
  */
-export const SUPPORTED_VPC_EGRESS_SETTINGS = [
-  'PRIVATE_RANGES_ONLY',
-  'ALL_TRAFFIC',
-] as const;
-
-/**
- * A valid VPC Egress setting.
- */
-export type VpcEgressSetting = typeof SUPPORTED_VPC_EGRESS_SETTINGS[number];
+export type VpcEgressSetting = 'PRIVATE_RANGES_ONLY' | 'ALL_TRAFFIC';
 
 /**
  * List of available options for IngressSettings.
  */
-export const SUPPORTED_INGRESS_SETTINGS = [
-  'ALLOW_ALL',
-  'ALLOW_INTERNAL_ONLY',
-  'ALLOW_INTERNAL_AND_GCLB',
-] as const;
-
-export type IngressSetting = typeof SUPPORTED_INGRESS_SETTINGS[number];
+export type IngressSetting =
+  | 'ALLOW_ALL'
+  | 'ALLOW_INTERNAL_ONLY'
+  | 'ALLOW_INTERNAL_AND_GCLB';
 
 /**
  * GlobalOptions are options that can be set across an entire project.
@@ -148,6 +105,11 @@ export interface GlobalOptions {
    * Timeout for the function in sections, possible values are 0 to 540.
    * HTTPS functions can specify a higher timeout.
    * A value of null restores the default of 60s
+   * The minimum timeout for a gen 2 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)
    */
   timeoutSeconds?: number | null;
 
@@ -170,6 +132,7 @@ export interface GlobalOptions {
    * Can only be applied to functions running on Cloud Functions v2.
    * 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.
    */
   concurrency?: number | null;
 
@@ -246,7 +209,7 @@ export function getGlobalOptions(): GlobalOptions {
 }
 
 /**
- * Options that can be set on an individual event-handling Cloud Function.
+ * Additional fields that can be set on any event-handling Cloud Function.
  */
 export interface EventHandlerOptions extends GlobalOptions {
   retry?: boolean;
@@ -361,6 +324,7 @@ export function optionsToEndpoint(
 
 /**
  * @hidden
+ * @alpha
  */
 export function __getSpec(): {
   globalOptions: GlobalOptions;