diff --git a/packages/@aws-cdk/integ-tests/lib/assertions/providers/lambda-handler/index.ts b/packages/@aws-cdk/integ-tests/lib/assertions/providers/lambda-handler/index.ts
index 24da9123f04a5..8873d83b8981c 100644
--- a/packages/@aws-cdk/integ-tests/lib/assertions/providers/lambda-handler/index.ts
+++ b/packages/@aws-cdk/integ-tests/lib/assertions/providers/lambda-handler/index.ts
@@ -7,6 +7,8 @@ export async function handler(event: AWSLambda.CloudFormationCustomResourceEvent
   console.log(`Event: ${JSON.stringify({ ...event, ResponseURL: '...' })}`);
   const provider = createResourceHandler(event, context);
   try {
+    // if we are deleting the custom resource, just respond
+    // with 'SUCCESS' since there is nothing to do.
     if (event.RequestType === 'Delete') {
       await provider.respond({
         status: 'SUCCESS',
@@ -16,6 +18,8 @@ export async function handler(event: AWSLambda.CloudFormationCustomResourceEvent
     }
     const result = await provider.handle();
     const actualPath = event.ResourceProperties.actualPath;
+    // if we are providing a path to make the assertion at, that means that we have
+    // flattened the response, otherwise the path to assert against in the entire response
     const actual = actualPath ? (result as { [key: string]: string })[`apiCallResponse.${actualPath}`] : (result as types.AwsApiCallResult).apiCallResponse;
     if ('expected' in event.ResourceProperties) {
       const assertion = new AssertionHandler({
@@ -31,6 +35,7 @@ export async function handler(event: AWSLambda.CloudFormationCustomResourceEvent
         await provider.respond({
           status: 'SUCCESS',
           reason: 'OK',
+          // return both the result of the API call _and_ the assertion results
           data: {
             ...assertionResult,
             ...result,
diff --git a/packages/@aws-cdk/integ-tests/lib/assertions/providers/lambda-handler/sdk.ts b/packages/@aws-cdk/integ-tests/lib/assertions/providers/lambda-handler/sdk.ts
index 9be89bf7df9d7..51d677b81084c 100644
--- a/packages/@aws-cdk/integ-tests/lib/assertions/providers/lambda-handler/sdk.ts
+++ b/packages/@aws-cdk/integ-tests/lib/assertions/providers/lambda-handler/sdk.ts
@@ -16,6 +16,8 @@ export function flatten(object: object): { [key: string]: any } {
       return [].concat(...Object.keys(child)
         .map(key => {
           let childKey = Buffer.isBuffer(child[key]) ? child[key].toString('utf8') : child[key];
+          // if the value is a json string then treat it as an object
+          // and keep recursing. This allows for easier assertions against complex json strings
           if (typeof childKey === 'string') {
             childKey = isJsonString(childKey);
           }
diff --git a/packages/@aws-cdk/integ-tests/lib/assertions/sdk.ts b/packages/@aws-cdk/integ-tests/lib/assertions/sdk.ts
index e136236b1518a..7f107f3ecd8d3 100644
--- a/packages/@aws-cdk/integ-tests/lib/assertions/sdk.ts
+++ b/packages/@aws-cdk/integ-tests/lib/assertions/sdk.ts
@@ -66,6 +66,8 @@ export class AwsApiCall extends ApiCallBase {
     // Needed so that all the policies set up by the provider should be available before the custom resource is provisioned.
     this.apiCallResource.node.addDependency(this.provider);
 
+    // if expectedResult has been configured then that means
+    // we are making assertions and we should output the results
     Aspects.of(this).add({
       visit(node: IConstruct) {
         if (node instanceof AwsApiCall) {