Docs review for v2.https (#1109)

* Docs review for v2.https

* PR fixes

* pr feedback

* pr feedback

Author: joehan

src/common/providers/https.ts

@@ -36,6 +36,7 @@ const JWT_REGEX = /^[a-zA-Z0-9\-_=]+?\.[a-zA-Z0-9\-_=]+?\.([a-zA-Z0-9\-_=]+)?$/;
 
 /** @hidden */
 export interface Request extends express.Request {
+  /** The wire format representation of the request body. */
   rawBody: Buffer;
 }
 
@@ -176,37 +177,53 @@ export interface CallableRequest<T = any> {
  * https://github.com/grpc/grpc/blob/master/doc/statuscodes.md
  *
  * Possible values:
- * - 'cancelled': The operation was cancelled (typically by the caller).
- * - 'unknown': Unknown error or an error from a different error domain.
- * - 'invalid-argument': Client specified an invalid argument. Note that this
- *   differs from 'failed-precondition'. 'invalid-argument' indicates
+ *
+ * - `cancelled`: The operation was cancelled (typically by the caller).
+ *
+ * - `unknown`: Unknown error or an error from a different error domain.
+ *
+ * - `invalid-argument`: Client specified an invalid argument. Note that this
+ *   differs from `failed-precondition`. `invalid-argument` indicates
  *   arguments that are problematic regardless of the state of the system
  *   (e.g. an invalid field name).
- * - 'deadline-exceeded': Deadline expired before operation could complete.
+ *
+ * - `deadline-exceeded`: Deadline expired before operation could complete.
  *   For operations that change the state of the system, this error may be
  *   returned even if the operation has completed successfully. For example,
  *   a successful response from a server could have been delayed long enough
  *   for the deadline to expire.
- * - 'not-found': Some requested document was not found.
- * - 'already-exists': Some document that we attempted to create already
+ *
+ * - `not-found`: Some requested document was not found.
+ *
+ * - `already-exists`: Some document that we attempted to create already
  *   exists.
- * - 'permission-denied': The caller does not have permission to execute the
+ *
+ * - `permission-denied`: The caller does not have permission to execute the
  *   specified operation.
- * - 'resource-exhausted': Some resource has been exhausted, perhaps a
+ *
+ * - `resource-exhausted`: Some resource has been exhausted, perhaps a
  *   per-user quota, or perhaps the entire file system is out of space.
- * - 'failed-precondition': Operation was rejected because the system is not
+ *
+ * - `failed-precondition`: Operation was rejected because the system is not
  *   in a state required for the operation's execution.
- * - 'aborted': The operation was aborted, typically due to a concurrency
+ *
+ * - `aborted`: The operation was aborted, typically due to a concurrency
  *   issue like transaction aborts, etc.
- * - 'out-of-range': Operation was attempted past the valid range.
- * - 'unimplemented': Operation is not implemented or not supported/enabled.
- * - 'internal': Internal errors. Means some invariants expected by
+ *
+ * - `out-of-range`: Operation was attempted past the valid range.
+ *
+ * - `unimplemented`: Operation is not implemented or not supported/enabled.
+ *
+ * - `internal`: Internal errors. Means some invariants expected by
  *   underlying system has been broken. If you see one of these errors,
  *   something is very broken.
- * - 'unavailable': The service is currently unavailable. This is most likely
+ *
+ * - `unavailable`: The service is currently unavailable. This is most likely
  *   a transient condition and may be corrected by retrying with a backoff.
- * - 'data-loss': Unrecoverable data loss or corruption.
- * - 'unauthenticated': The request does not have valid authentication
+ *
+ * - `data-loss`: Unrecoverable data loss or corruption.
+ *
+ * - `unauthenticated`: The request does not have valid authentication
  *   credentials for the operation.
  */
 export type FunctionsErrorCode =
@@ -326,6 +343,9 @@ export class HttpsError extends Error {
     this.httpErrorCode = errorCodeMap[code];
   }
 
+  /**
+   * Returns a JSON-serializable representation of this object.
+   */
   public toJSON(): HttpErrorWireFormat {
     const {
       details,

src/v2/providers/https.ts

@@ -38,31 +38,62 @@ import { GlobalOptions, SupportedRegion } from '../options';
 export { Request, CallableRequest, FunctionsErrorCode, HttpsError };
 
 /**
- * Options that can be set on an individual HTTPS Cloud Function.
+ * Options that can be set on an individual HTTPS function.
  */
 export interface HttpsOptions extends Omit<GlobalOptions, 'region'> {
-  /* HTTP functions can override and specify more than one regions. */
+  /** HTTP functions can override global options and can specify multiple regions to deploy to. */
   region?: SupportedRegion | string | Array<SupportedRegion | string>;
+  /** If true, allows CORS on requests to this function.
+   * If this is a `string` or `RegExp`, allows requests from domains that match the provided value.
+   * If this is an `Array`, allows requests from domains matching at least one entry of the array.
+   * Defaults to true for {@link CallableFunction}s and false otherwise.
+   */
   cors?: string | boolean | RegExp | Array<string | RegExp>;
 }
 
+/**
+ * Handles HTTPS requests.
+ */
 export type HttpsFunction = ((
+  /** An Express request object representing the HTTPS call to the function. */
   req: Request,
+  /** An Express response object, for this function to respond to callers. */
   res: express.Response
 ) => void | Promise<void>) & {
+  /** @alpha */
   __trigger?: unknown;
+  /** @alpha */
   __endpoint: ManifestEndpoint;
 };
+
+/**
+ * Creates a callable method for clients to call using a Firebase SDK.
+ */
 export interface CallableFunction<T, Return> extends HttpsFunction {
+  /** Executes the handler function with the provided data as input. Used for unit testing.
+   * @param data - An input for the handler function.
+   * @returns The output of the handler function.
+   */
   run(data: CallableRequest<T>): Return;
 }
+/**
+ * Handles HTTPS requests.
+ * @param opts - Options to set on this function
+ * @param handler - A function that takes a {@link Request} and response object, same signature as an Express app.
+ * @returns A function that you can export and deploy.
+ */
 export function onRequest(
   opts: HttpsOptions,
   handler: (
     request: Request,
     response: express.Response
   ) => void | Promise<void>
 ): HttpsFunction;
+/**
+ * Handles HTTPS requests.
+ * @param handler - A function that takes a {@link Request} and response object, same signature as an Express app.
+ * @returns A function that you can export and deploy.
+ */
 export function onRequest(
   handler: (
     request: Request,
@@ -160,10 +191,21 @@ export function onRequest(
   return handler as HttpsFunction;
 }
 
+/**
+ * Declares a callable method for clients to call using a Firebase SDK.
+ * @param opts - Options to set on this function.
+ * @param handler - A function that takes a {@link CallableRequest}.
+ * @returns A function that you can export and deploy.
+ */
 export function onCall<T = any, Return = any | Promise<any>>(
   opts: HttpsOptions,
   handler: (request: CallableRequest<T>) => Return
 ): CallableFunction<T, Return>;
+/**
+ * Declares a callable method for clients to call using a Firebase SDK.
+ * @param handler - A function that takes a {@link CallableRequest}.
+ * @returns A function that you can export and deploy.
+ */
 export function onCall<T = any, Return = any | Promise<any>>(
   handler: (request: CallableRequest<T>) => Return
 ): CallableFunction<T, Return>;