diff --git a/packages/aws-cdk/README.md b/packages/aws-cdk/README.md
index d76e7d9ea612d..9a0c23a304b24 100644
--- a/packages/aws-cdk/README.md
+++ b/packages/aws-cdk/README.md
@@ -430,7 +430,16 @@ For this reason, only use it for development purposes.
 **⚠ Note #2**: This command is considered experimental,
 and might have breaking changes in the future.
 
-**⚠ Note #3**: Expected defaults for certain parameters may be different with the hotswap parameter. For example, an ECS service's minimum healthy percentage will currently be set to 0. Please review the source accordingly if this occurs. 
+**⚠ Note #3**: Expected defaults for certain parameters may be different with the hotswap parameter. For example, an ECS service's minimum healthy percentage will currently be set to 0. Please review the source accordingly if this occurs.
+
+**⚠ Note #4**: Only usage of certain [CloudFormation intrinsic functions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html) are supported as part of a hotswapped deployment. At time of writing, these are:
+- `Ref`
+- `Fn::GetAtt`
+- `Fn::ImportValue`
+- `Fn::Join`
+- `Fn::Select`
+- `Fn::Split`
+- `Fn::Sub`
 
 ### `cdk watch`
 
diff --git a/packages/aws-cdk/lib/api/evaluate-cloudformation-template.ts b/packages/aws-cdk/lib/api/evaluate-cloudformation-template.ts
index 7a1238797e193..473ae72527a79 100644
--- a/packages/aws-cdk/lib/api/evaluate-cloudformation-template.ts
+++ b/packages/aws-cdk/lib/api/evaluate-cloudformation-template.ts
@@ -188,6 +188,14 @@ export class EvaluateCloudFormationTemplate {
 
   public async evaluateCfnExpression(cfnExpression: any): Promise<any> {
     const self = this;
+    /**
+     * Evaluates CloudFormation intrinsic functions
+     *
+     * Note that supported intrinsic functions are documented in README.md -- please update
+     * list of supported functions when adding new evaluations
+     *
+     * See: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html
+     */
     class CfnIntrinsics {
       public evaluateIntrinsic(intrinsic: Intrinsic): any {
         const intrinsicFunc = (this as any)[intrinsic.name];