chore(core): make examples compile

packages/@aws-cdk/core/README.md

@@ -237,6 +237,8 @@ this purpose.
 use the region and account of the stack you're calling it on:
 
 ```ts
+declare const stack: Stack;
+
 // Builds "arn:<PARTITION>:lambda:<REGION>:<ACCOUNT>:function:MyFunction"
 stack.formatArn({
   service: 'lambda',
@@ -252,6 +254,8 @@ but in case of a deploy-time value be aware that the result will be another
 deploy-time value which cannot be inspected in the CDK application.
 
 ```ts
+declare const stack: Stack;
+
 // Extracts the function name out of an AWS Lambda Function ARN
 const arnComponents = stack.parseArn(arn, ':');
 const functionName = arnComponents.resourceName;
@@ -383,7 +387,11 @@ examples ensures that only a single SNS topic is defined:
 function getOrCreate(scope: Construct): sns.Topic {
   const stack = Stack.of(scope);
   const uniqueid = 'GloballyUniqueIdForSingleton'; // For example, a UUID from `uuidgen`
-  return stack.node.tryFindChild(uniqueid) as sns.Topic  ?? new sns.Topic(stack, uniqueid);
+  const existing = stack.node.tryFindChild(uniqueid);
+  if (existing) {
+    return existing as sns.Topic;
+  }
+  return new sns.Topic(stack, uniqueid);
 }
 ```
 
@@ -816,6 +824,8 @@ since the top-level key is an unresolved token. The call to `findInMap` will ret
 `{ "Fn::FindInMap": [ "RegionTable", { "Ref": "AWS::Region" }, "regionName" ] }`.
 
 ```ts
+declare const regionTable: CfnMapping;
+
 regionTable.findInMap(Aws.REGION, 'regionName');
 ```
 

packages/@aws-cdk/core/lib/assets.ts

@@ -247,14 +247,14 @@ export interface FileAssetLocation {
   /**
    * The HTTP URL of this asset on Amazon S3.
    *
-   * @example https://s3-us-east-1.amazonaws.com/mybucket/myobject
+   * Example value: `https://s3-us-east-1.amazonaws.com/mybucket/myobject`
    */
   readonly httpUrl: string;
 
   /**
    * The S3 URL of this asset on Amazon S3.
    *
-   * @example s3://mybucket/myobject
+   * Example value: `s3://mybucket/myobject`
    */
   readonly s3ObjectUrl: string;
 

packages/@aws-cdk/core/lib/bundling.ts

@@ -16,7 +16,7 @@ export interface BundlingOptions {
   /**
    * The entrypoint to run in the Docker container.
    *
-   * @example ['/bin/sh', '-c']
+   * Example value: `['/bin/sh', '-c']`
    *
    * @see https://docs.docker.com/engine/reference/builder/#entrypoint
    *
@@ -27,7 +27,7 @@ export interface BundlingOptions {
   /**
    * The command to run in the Docker container.
    *
-   * @example ['npm', 'install']
+   * Example value: `['npm', 'install']`
    *
    * @see https://docs.docker.com/engine/reference/run/
    *
@@ -447,7 +447,7 @@ export interface DockerBuildOptions {
   /**
    * Set platform if server is multi-platform capable. _Requires Docker Engine API v1.38+_.
    *
-   * @example 'linux/amd64'
+   * Example value: `linux/amd64`
    *
    * @default - no platform specified
    */

packages/@aws-cdk/core/lib/construct-compat.ts

@@ -343,7 +343,7 @@ export class ConstructNode {
    * will be excluded from the calculation. In those cases constructs in the
    * same tree may have the same addreess.
    *
-   * @example c83a2846e506bcc5f10682b564084bca2d275709ee
+   * Example value: `c83a2846e506bcc5f10682b564084bca2d275709ee`
    */
   public get addr(): string { return this._actualNode.addr; }
 

packages/@aws-cdk/core/lib/custom-resource-provider/custom-resource-provider.ts

@@ -36,12 +36,23 @@ export interface CustomResourceProviderProps {
    * A set of IAM policy statements to include in the inline policy of the
    * provider's lambda function.
    *
+   * **Please note**: these are direct IAM JSON policy blobs, *not* `iam.PolicyStatement`
+   * objects like you will see in the rest of the CDK.
+   *
    * @default - no additional inline policy
    *
    * @example
-   *
-   *   [{ Effect: 'Allow', Action: 's3:PutObject*', Resource: '*' }]
-   *
+   * const provider = CustomResourceProvider.getOrCreateProvider(this, 'Custom::MyCustomResourceType', {
+   *   codeDirectory: `${__dirname}/my-handler`,
+   *   runtime: CustomResourceProviderRuntime.NODEJS_12_X,
+   *   policyStatements: [
+   *     {
+   *       Effect: 'Allow',
+   *       Action: 's3:PutObject*',
+   *       Resource: '*',
+   *     }
+   *   ],
+   * });
    */
   readonly policyStatements?: any[];
 
@@ -144,11 +155,15 @@ export class CustomResourceProvider extends CoreConstruct {
    * `serviceToken` when defining a custom resource.
    *
    * @example
-   *   new CustomResource(this, 'MyCustomResource', {
-   *     // ...
-   *     serviceToken: myProvider.serviceToken, // <--- here
-   *   })
+   * declare const myProvider: CustomResourceProvider;
    *
+   * new CustomResource(this, 'MyCustomResource', {
+   *   serviceToken: myProvider.serviceToken,
+   *   properties: {
+   *     myPropertyOne: 'one',
+   *     myPropertyTwo: 'two',
+   *   },
+   * });
    */
   public readonly serviceToken: string;
 

packages/@aws-cdk/core/lib/nested-stack.ts

@@ -155,8 +155,8 @@ export class NestedStack extends Stack {
    * - If this is referenced from the parent stack, it will return a token that parses the name from the stack ID.
    * - If this is referenced from the context of the nested stack, it will return `{ "Ref": "AWS::StackName" }`
    *
+   * Example value: `mystack-mynestedstack-sggfrhxhum7w`
    * @attribute
-   * @example mystack-mynestedstack-sggfrhxhum7w
    */
   public get stackName() {
     return this._contextualStackName;
@@ -169,8 +169,8 @@ export class NestedStack extends Stack {
    * - If this is referenced from the parent stack, it will return `{ "Ref": "LogicalIdOfNestedStackResource" }`.
    * - If this is referenced from the context of the nested stack, it will return `{ "Ref": "AWS::StackId" }`
    *
+   * Example value: `arn:aws:cloudformation:us-east-2:123456789012:stack/mystack-mynestedstack-sggfrhxhum7w/f449b250-b969-11e0-a185-5081d0136786`
    * @attribute
-   * @example "arn:aws:cloudformation:us-east-2:123456789012:stack/mystack-mynestedstack-sggfrhxhum7w/f449b250-b969-11e0-a185-5081d0136786"
    */
   public get stackId() {
     return this._contextualStackId;

packages/@aws-cdk/core/lib/removal-policy.ts

@@ -19,8 +19,10 @@
  * as shown in the following example:
  *
  * ```ts
- * const cfnBucket = bucket.node.findChild('Resource') as cdk.CfnResource;
- * cfnBucket.applyRemovalPolicy(cdk.RemovalPolicy.DESTROY);
+ * declare const bucket: s3.Bucket;
+ *
+ * const cfnBucket = bucket.node.findChild('Resource') as CfnResource;
+ * cfnBucket.applyRemovalPolicy(RemovalPolicy.DESTROY);
  * ```
  */
 export enum RemovalPolicy {

packages/@aws-cdk/core/lib/stack.ts

@@ -280,7 +280,7 @@ export class Stack extends CoreConstruct implements ITaggable {
    * The name of the CloudFormation template file emitted to the output
    * directory during synthesis.
    *
-   * @example 'MyStack.template.json'
+   * Example value: `MyStack.template.json`
    */
   public readonly templateFile: string;
 
@@ -711,11 +711,13 @@ export class Stack extends CoreConstruct implements ITaggable {
    *
    * Duplicate values are removed when stack is synthesized.
    *
-   * @example stack.addTransform('AWS::Serverless-2016-10-31')
-   *
    * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-section-structure.html
-   *
    * @param transform The transform to add
+   *
+   * @example
+   * declare const stack: Stack;
+   *
+   * stack.addTransform('AWS::Serverless-2016-10-31')
    */
   public addTransform(transform: string) {
     if (!this.templateOptions.transforms) {

packages/@aws-cdk/core/package.json

@@ -28,7 +28,14 @@
         ]
       }
     },
-    "projectReferences": true
+    "projectReferences": true,
+    "metadata": {
+      "jsii": {
+        "rosetta": {
+          "strict": true
+        }
+      }
+    }
   },
   "repository": {
     "type": "git",

packages/@aws-cdk/core/rosetta/default.ts-fixture

@@ -27,6 +27,7 @@ import {
   Duration,
   Fn,
   IConstruct,
+  RemovalPolicy,
   SecretValue,
   Size,
   SizeRoundingBehavior,
@@ -47,15 +48,27 @@ declare const functionProps: lambda.FunctionProps;
 declare const isCompleteHandler: lambda.Function;
 declare const myBucket: s3.IBucket;
 declare const myFunction: lambda.IFunction;
-declare const myProvider: CustomResourceProvider;
 declare const myTopic: sns.ITopic;
 declare const onEventHandler: lambda.Function;
 declare const resourceProps: CfnResourceProps;
-declare const stack: Stack;
 
 declare class MyStack extends Stack {}
 declare class YourStack extends Stack {}
 
+class StackThatProvidesABucket extends Stack {
+  public readonly bucket!: s3.IBucket;
+}
+
+interface StackThatExpectsABucketProps extends StackProps {
+  readonly bucket: s3.IBucket;
+}
+
+class StackThatExpectsABucket extends Stack {
+  constructor(scope: Construct, id: string, props: StackThatExpectsABucketProps) {
+    super(scope, id, props);
+  }
+}
+
 class fixture$construct extends Construct {
   public constructor(scope: Construct, id: string) {
     super(scope, id);

packages/aws-cdk-lib/README.md

@@ -270,6 +270,8 @@ this purpose.
 use the region and account of the stack you're calling it on:
 
 ```ts
+declare const stack: Stack;
+
 // Builds "arn:<PARTITION>:lambda:<REGION>:<ACCOUNT>:function:MyFunction"
 stack.formatArn({
   service: 'lambda',
@@ -285,6 +287,8 @@ but in case of a deploy-time value be aware that the result will be another
 deploy-time value which cannot be inspected in the CDK application.
 
 ```ts
+declare const stack: Stack;
+
 // Extracts the function name out of an AWS Lambda Function ARN
 const arnComponents = stack.parseArn(arn, ':');
 const functionName = arnComponents.resourceName;
@@ -416,7 +420,11 @@ examples ensures that only a single SNS topic is defined:
 function getOrCreate(scope: Construct): sns.Topic {
   const stack = Stack.of(scope);
   const uniqueid = 'GloballyUniqueIdForSingleton'; // For example, a UUID from `uuidgen`
-  return stack.node.tryFindChild(uniqueid) as sns.Topic  ?? new sns.Topic(stack, uniqueid);
+  const existing = stack.node.tryFindChild(uniqueid);
+  if (existing) {
+    return existing as sns.Topic;
+  }
+  return new sns.Topic(stack, uniqueid);
 }
 ```
 
@@ -849,6 +857,8 @@ since the top-level key is an unresolved token. The call to `findInMap` will ret
 `{ "Fn::FindInMap": [ "RegionTable", { "Ref": "AWS::Region" }, "regionName" ] }`.
 
 ```ts
+declare const regionTable: CfnMapping;
+
 regionTable.findInMap(Aws.REGION, 'regionName');
 ```