docs: rereview jsdoc in light of new copilot instructions

Author: tstephen-nhs

packages/cdkConstructs/src/constructs/RestApiGateway/StateMachineEndpoint.ts

@@ -6,6 +6,7 @@ import {stateMachineRequestTemplate} from "./templates/stateMachineRequest.js"
 import {stateMachine200ResponseTemplate, stateMachineErrorResponseTemplate} from "./templates/stateMachineResponses.js"
 import {ExpressStateMachine} from "../StateMachine.js"
 
+/** Parameters used to create an API endpoint backed by a Step Functions Express workflow. */
 export interface StateMachineEndpointProps {
   /** Parent API resource under which the state machine endpoint is added. */
   parentResource: IResource
@@ -21,6 +22,7 @@ export interface StateMachineEndpointProps {
 
 /** Adds an API Gateway resource/method that starts an Express Step Functions execution. */
 export class StateMachineEndpoint extends Construct {
+  /** API resource created by this construct. */
   resource: IResource
 
   /** Wires request and response mapping templates for JSON and FHIR payload flows. */

packages/cdkConstructs/src/constructs/RestApiGateway/templates/stateMachineRequest.ts

@@ -1,4 +1,7 @@
 /* eslint-disable max-len */
+/**
+ * @returns API Gateway request mapping template for StartExecution payloads.
+ */
 export const stateMachineRequestTemplate = (stateMachineArn: string) => {
   return `## Velocity Template used for API Gateway request mapping template
 ## "@@" is used here as a placeholder for '"' to avoid using escape characters.

packages/cdkConstructs/src/constructs/RestApiGateway/templates/stateMachineResponses.ts

@@ -1,4 +1,5 @@
 /* eslint-disable max-len */
+/** VTL response template that unwraps successful workflow output and forwards status and headers. */
 export const stateMachine200ResponseTemplate = `#set($payload = $util.parseJson($input.path('$.output')))
 #set($context.responseOverride.status = $payload.Payload.statusCode)
 #set($allHeaders = $payload.Payload.headers)
@@ -56,5 +57,8 @@ const getOperationOutcome = (status: string) => {
   })
 }
 
+/**
+ * @returns VTL response template that maps workflow failures to FHIR OperationOutcome payloads.
+ */
 export const stateMachineErrorResponseTemplate = (status: string) => `#set($context.responseOverride.header["Content-Type"] ="application/fhir+json")
 ${getOperationOutcome(status)}`

packages/cdkConstructs/src/constructs/StateMachine.ts

@@ -22,6 +22,10 @@ import {Construct} from "constructs"
 import {CfnDeliveryStream} from "aws-cdk-lib/aws-kinesisfirehose"
 import {ACCOUNT_RESOURCES, LAMBDA_RESOURCES} from "../constants"
 
+/**
+ * Configuration for provisioning an Express Step Functions state machine
+ * with logging and optional Splunk forwarding.
+ */
 export interface StateMachineProps {
   /** Stack name, used as prefix for resource naming and DNS records. */
   readonly stackName: string
@@ -60,8 +64,12 @@ export interface StateMachineProps {
   readonly addSplunkSubscriptionFilter?: boolean
 }
 
+/** Creates an Express Step Functions workflow with CloudWatch logging and invoke permissions. */
 export class ExpressStateMachine extends Construct {
+  /** Managed policy that grants permission to start this workflow. */
   public readonly executionPolicy: ManagedPolicy
+
+  /** Created Step Functions state machine resource. */
   public readonly stateMachine: StateMachine
 
   /**