chore: udpate ts-doc annotations (#603)

Author: matthewrobertson

docs/generated/api.json

@@ -175,7 +175,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@google-cloud/functions-framework!cloudEvent:function(1)",
-          "docComment": "/**\n * Register a function that handles CloudEvents.\n *\n * @param functionName - the name of the function\n *\n * @param handler - the function to trigger when handling CloudEvents\n *\n * @public\n */\n",
+          "docComment": "/**\n * Register a function that handles CloudEvents.\n *\n * @param functionName - The name of the function\n *\n * @param handler - The function to trigger when handling CloudEvents\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -949,7 +949,7 @@
         {
           "kind": "Function",
           "canonicalReference": "@google-cloud/functions-framework!http:function(1)",
-          "docComment": "/**\n * Register a function that responds to HTTP requests.\n *\n * @param functionName - the name of the function\n *\n * @param handler - the function to invoke when handling HTTP requests\n *\n * @public\n */\n",
+          "docComment": "/**\n * Register a function that responds to HTTP requests.\n *\n * @param functionName - The name of the function\n *\n * @param handler - The function to invoke when handling HTTP requests\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -1125,7 +1125,7 @@
             {
               "kind": "MethodSignature",
               "canonicalReference": "@google-cloud/functions-framework!InvocationFormat#deserializeRequest:member(1)",
-              "docComment": "/**\n * Creates an instance of the request type from an invocation request.\n *\n * @param request - the request body as raw bytes\n */\n",
+              "docComment": "/**\n * Creates an instance of the request type from an invocation request.\n *\n * @param request - The request body as raw bytes\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -1180,7 +1180,7 @@
             {
               "kind": "MethodSignature",
               "canonicalReference": "@google-cloud/functions-framework!InvocationFormat#serializeResponse:member(1)",
-              "docComment": "/**\n * Writes the response type to the invocation result.\n *\n * @param responseWriter - interface for writing to the invocation result\n *\n * @param response - the response object\n */\n",
+              "docComment": "/**\n * Writes the response type to the invocation result.\n *\n * @param responseWriter - Interface for writing to the invocation result\n *\n * @param response - The response object\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",

src/cloud_events.ts

@@ -36,7 +36,7 @@ export const CE_SERVICE = {
  *
  * {@link https://github.com/cloudevents/spec/blob/main/http-protocol-binding.md#3-http-message-mapping}
  *
- * @param req - Express request object.
+ * @param req - Express request object
  * @return True if the request is a CloudEvents event in binary content mode,
  *     false otherwise.
  */
@@ -53,8 +53,8 @@ export function isBinaryCloudEvent(req: express.Request): boolean {
  * Returns a CloudEvents context from the given CloudEvents request. Context
  * attributes are retrieved from request headers.
  *
- * @param req Express request object.
- * @return CloudEvents context.
+ * @param req - Express request object
+ * @return CloudEvents context
  */
 export function getBinaryCloudEventContext(
   req: express.Request

src/function_registry.ts

@@ -56,7 +56,7 @@ const register = <T = unknown, U = unknown>(
  * - must be <= 63 characters
  * - must start with a letter
  * - must end with a letter or number
- * @param functionName the function name
+ * @param functionName - The function name
  * @returns true if the function name is valid
  */
 export const isValidFunctionName = (functionName: string): boolean => {
@@ -67,9 +67,9 @@ export const isValidFunctionName = (functionName: string): boolean => {
 
 /**
  * Get a declaratively registered function
- * @param functionName the name with which the function was registered
- * @returns the registered function and signature type or undefined no function matching
- * the provided name has been registered.
+ * @param functionName - The name with which the function was registered
+ * @returns The registered function and signature type or undefined no function matching
+ * the provided name has been registered
  */
 export const getRegisteredFunction = (
   functionName: string
@@ -80,8 +80,8 @@ export const getRegisteredFunction = (
 
 /**
  * Register a function that responds to HTTP requests.
- * @param functionName - the name of the function
- * @param handler - the function to invoke when handling HTTP requests
+ * @param functionName - The name of the function
+ * @param handler - The function to invoke when handling HTTP requests
  * @public
  */
 export const http = (functionName: string, handler: HttpFunction): void => {
@@ -90,8 +90,8 @@ export const http = (functionName: string, handler: HttpFunction): void => {
 
 /**
  * Register a function that handles CloudEvents.
- * @param functionName - the name of the function
- * @param handler - the function to trigger when handling CloudEvents
+ * @param functionName - The name of the function
+ * @param handler - The function to trigger when handling CloudEvents
  * @public
  */
 export const cloudEvent = <T = unknown>(
@@ -103,8 +103,8 @@ export const cloudEvent = <T = unknown>(
 
 /**
  * Register a function that handles strongly typed invocations.
- * @param functionName - the name of the function
- * @param handler - the function to trigger
+ * @param functionName - The name of the function
+ * @param handler - The function to trigger
  * @internal
  */
 export const typed = <T, U>(

src/function_wrappers.ts

@@ -41,8 +41,8 @@ type OnDoneCallback = (err: Error | null, result: any) => void;
 
 /**
  * Get a completion handler that can be used to signal completion of an event function.
- * @param res the response object of the request the completion handler is for.
- * @returns an OnDoneCallback for the provided request.
+ * @param res - The response object of the request the completion handler is for
+ * @returns An OnDoneCallback for the provided request.
  */
 const getOnDoneCallback = (res: Response): OnDoneCallback => {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -58,8 +58,8 @@ const getOnDoneCallback = (res: Response): OnDoneCallback => {
 
 /**
  * Helper function to parse a CloudEvent object from an HTTP request.
- * @param req an Express HTTP request
- * @returns a CloudEvent parsed from the request
+ * @param req - An Express HTTP request
+ * @returns A CloudEvent parsed from the request
  */
 const parseCloudEventRequest = (req: Request): CloudEvent<unknown> => {
   let cloudEvent = req.body;
@@ -77,8 +77,8 @@ const parseCloudEventRequest = (req: Request): CloudEvent<unknown> => {
 /**
  * Helper function to background event context and data payload object from an HTTP
  * request.
- * @param req an Express HTTP request
- * @returns the data playload and event context parsed from the request
+ * @param req - An Express HTTP request
+ * @returns The data playload and event context parsed from the request
  */
 const parseBackgroundEvent = (req: Request): {data: {}; context: Context} => {
   const event = req.body;
@@ -100,8 +100,8 @@ const parseBackgroundEvent = (req: Request): {data: {}; context: Context} => {
 /**
  * Wraps the provided function into an Express handler function with additional
  * instrumentation logic.
- * @param execute Runs user's function.
- * @return An Express handler function.
+ * @param execute - Runs user's function
+ * @return An Express handler function
  */
 const wrapHttpFunction = (execute: HttpFunction): RequestHandler => {
   return (req: Request, res: Response) => {
@@ -132,8 +132,8 @@ const wrapHttpFunction = (execute: HttpFunction): RequestHandler => {
 
 /**
  * Wraps an async CloudEvent function in an express RequestHandler.
- * @param userFunction User's function.
- * @return An Express hander function that invokes the user function.
+ * @param userFunction - User's function
+ * @return An Express hander function that invokes the user function
  */
 const wrapCloudEventFunction = (
   userFunction: CloudEventFunction
@@ -153,8 +153,8 @@ const wrapCloudEventFunction = (
 
 /**
  * Wraps callback style CloudEvent function in an express RequestHandler.
- * @param userFunction User's function.
- * @return An Express hander function that invokes the user function.
+ * @param userFunction - User's function
+ * @return An Express hander function that invokes the user function
  */
 const wrapCloudEventFunctionWithCallback = (
   userFunction: CloudEventFunctionWithCallback
@@ -169,8 +169,8 @@ const wrapCloudEventFunctionWithCallback = (
 
 /**
  * Wraps an async event function in an express RequestHandler.
- * @param userFunction User's function.
- * @return An Express hander function that invokes the user function.
+ * @param userFunction - User's function
+ * @return An Express hander function that invokes the user function
  */
 const wrapEventFunction = (userFunction: EventFunction): RequestHandler => {
   const httpHandler = (req: Request, res: Response) => {
@@ -188,8 +188,8 @@ const wrapEventFunction = (userFunction: EventFunction): RequestHandler => {
 
 /**
  * Wraps a callback style event function in an express RequestHandler.
- * @param userFunction User's function.
- * @return An Express hander function that invokes the user function.
+ * @param userFunction - User's function
+ * @return An Express hander function that invokes the user function
  */
 const wrapEventFunctionWithCallback = (
   userFunction: EventFunctionWithCallback
@@ -204,7 +204,7 @@ const wrapEventFunctionWithCallback = (
 
 /**
  * Wraps a typed function in an express style RequestHandler.
- * @param userFunction User's function
+ * @param userFunction - User's function
  * @return An Express handler function that invokes the user function
  */
 const wrapTypedFunction = (typedFunction: TypedFunction): RequestHandler => {

src/functions.ts

@@ -198,15 +198,15 @@ export interface InvocationFormat<T, U> {
   /**
    * Creates an instance of the request type from an invocation request.
    *
-   * @param request - the request body as raw bytes
+   * @param request - The request body as raw bytes
    */
   deserializeRequest(request: InvocationRequest): T | Promise<T>;
 
   /**
    * Writes the response type to the invocation result.
    *
-   * @param responseWriter interface for writing to the invocation result
-   * @param response the response object
+   * @param responseWriter - Interface for writing to the invocation result
+   * @param response - The response object
    */
   serializeResponse(
     responseWriter: InvocationResponse,

src/invoker.ts

@@ -34,9 +34,9 @@ export const setLatestRes = (res: express.Response) => {
 
 /**
  * Sends back a response to the incoming request.
- * @param result Output from function execution.
- * @param err Error from function execution.
- * @param res Express response object.
+ * @param result - Output from function execution
+ * @param err - Error from function execution
+ * @param res - Express response object
  */
 
 export function sendResponse(
@@ -79,7 +79,7 @@ const killInstance = process.exit.bind(process, 16);
 
 /**
  * Enables registration of error handlers.
- * @param server HTTP server which invokes user's function.
+ * @param server - HTTP server which invokes user's function
  * @constructor
  */
 export class ErrorHandler {

src/loader.ts

@@ -174,7 +174,7 @@ export async function getUserFunction(
 /**
  * Returns resolved path to the module containing the user function.
  * Returns null if the module can not be identified.
- * @param codeLocation Directory with user's code.
+ * @param codeLocation - Directory with user's code
  * @return Resolved path or null.
  */
 function getFunctionModulePath(codeLocation: string): string | null {

src/logger.ts

@@ -25,9 +25,9 @@ const SEVERITY = 'severity';
 /**
  * Logs an error message and sends back an error response to the incoming
  * request.
- * @param err Error to be logged and sent.
- * @param res Express response object.
- * @param callback A function to be called synchronously.
+ * @param err - Error to be logged and sent
+ * @param res - Express response object
+ * @param callback - A function to be called synchronously
  */
 export function sendCrashResponse({
   err,

src/middleware/background_event_to_cloud_event.ts

@@ -62,8 +62,8 @@ const CE_SERVICE_TO_RESOURCE_RE = new Map([
 
 /**
  * Is this request a known GCF event that can be converted to a cloud event.
- * @param req the express request object
- * @returns true if this request can be converted to a CloudEvent
+ * @param req - The express request object
+ * @returns True if this request can be converted to a CloudEvent
  */
 const isConvertableBackgroundEvent = (req: Request): boolean => {
   const {body} = req;
@@ -79,8 +79,8 @@ const isConvertableBackgroundEvent = (req: Request): boolean => {
 
 /**
  * Convert the given HTTP request into the GCF Background Event data / context format.
- * @param body the express request object
- * @returns a marshalled background event
+ * @param body - The express request object
+ * @returns A marshalled background event
  */
 const getBackgroundEvent = (request: Request): LegacyEvent => {
   let {context} = request.body;
@@ -104,8 +104,8 @@ interface ParsedResource {
 
 /**
  * Splits a background event's resource into a CloudEvent service, resource, and subject.
- * @param context the GCF event context to parse.
- * @returns the CloudEvent service, resource and subject fields for the given GCF event context.
+ * @param context - The GCF event context to parse
+ * @returns The CloudEvent service, resource and subject fields for the given GCF event context
  */
 export const splitResource = (
   context: CloudFunctionsContext
@@ -159,9 +159,9 @@ export const splitResource = (
 /**
  * Express middleware to convert background GCF requests to Cloudevents. This enables functions
  * using the "cloudevent" signature type to accept requests from a background event producer.
- * @param req express request object
- * @param res express response object
- * @param next function used to pass control to the next middleware function in the stack
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param next - Function used to pass control to the next middleware function in the stack
  */
 export const backgroundEventToCloudEventMiddleware = (
   req: Request,

src/middleware/cloud_event_to_background_event.ts

@@ -62,8 +62,8 @@ const CE_SOURCE_REGEX = /\/\/([^/]+)\/(.+)/;
 
 /**
  * Is the given request a known CloudEvent that can be converted to a legacy event.
- * @param request express request object
- * @returns true if the request can be converted
+ * @param request - Express request object
+ * @returns True if the request can be converted
  */
 const isConvertableCloudEvent = (request: Request): boolean => {
   if (isBinaryCloudEvent(request)) {
@@ -75,8 +75,8 @@ const isConvertableCloudEvent = (request: Request): boolean => {
 
 /**
  * Splits a CloudEvent source string into resource and subject components.
- * @param source the cloud event source
- * @returns the parsed service and name components of the CE source string
+ * @param source - The cloud event source
+ * @returns The parsed service and name components of the CE source string
  */
 export const parseSource = (
   source: string
@@ -95,8 +95,8 @@ export const parseSource = (
 
 /**
  * Marshal a known GCP CloudEvent request the equivalent context/data legacy event format.
- * @param req express request object
- * @returns the request body of the equivalent legacy event request
+ * @param req - Express request object
+ * @returns The request body of the equivalent legacy event request
  */
 const marshalConvertableCloudEvent = (
   req: Request
@@ -173,9 +173,9 @@ const marshalConvertableCloudEvent = (
 /**
  * Express middleware to convert cloud event requests to legacy GCF events. This enables
  * functions using the "EVENT" signature type to accept requests from a cloud event producer.
- * @param req express request object
- * @param res express response object
- * @param next function used to pass control to the next middle middleware function in the stack
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param next - Function used to pass control to the next middle middleware function in the stack
  */
 export const cloudEventToBackgroundEventMiddleware = (
   req: Request,

src/options.ts

@@ -162,9 +162,9 @@ Documentation:
 /**
  * Parse the configurable framework options from the provided CLI arguments and
  * environment variables.
- * @param cliArgs the raw command line arguments
- * @param envVars the environment variables to parse options from
- * @returns the parsed options that should be used to configure the framework.
+ * @param cliArgs - The raw command line arguments
+ * @param envVars - The environment variables to parse options from
+ * @returns The parsed options that should be used to configure the framework
  */
 export const parseOptions = (
   cliArgs: string[] = process.argv,