chore(codepipeline): make examples compile (aws#17467)

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

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

@@ -16,14 +16,14 @@
 To construct an empty Pipeline:
 
 ```ts
-import * as codepipeline from '@aws-cdk/aws-codepipeline';
-
+// Construct an empty Pipeline
 const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline');
 ```
 
 To give the Pipeline a nice, human-readable name:
 
 ```ts
+// Give the Pipeline a nice, human-readable name
 const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
   pipelineName: 'MyPipeline',
 });
@@ -40,6 +40,7 @@ the creation of the Customer Master Keys by passing `crossAccountKeys: false`
 when defining the Pipeline:
 
 ```ts
+// Don't create Customer Master Keys
 const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
   crossAccountKeys: false,
 });
@@ -50,6 +51,7 @@ you can configure it by passing `enableKeyRotation: true` when creating the pipe
 Note that key rotation will incur an additional cost of **$1/month**.
 
 ```ts
+// Enable key rotation for the generated KMS key
 const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
   // ...
   enableKeyRotation: true,
@@ -61,6 +63,7 @@ const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
 You can provide Stages when creating the Pipeline:
 
 ```ts
+// Provide a Stage when creating a pipeline
 const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
   stages: [
     {
@@ -76,6 +79,8 @@ const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
 Or append a Stage to an existing Pipeline:
 
 ```ts
+// Append a Stage to an existing Pipeline
+declare const pipeline: codepipeline.Pipeline;
 const sourceStage = pipeline.addStage({
   stageName: 'Source',
   actions: [ // optional property
@@ -87,12 +92,17 @@ const sourceStage = pipeline.addStage({
 You can insert the new Stage at an arbitrary point in the Pipeline:
 
 ```ts
+// Insert a new Stage at an arbitrary point
+declare const pipeline: codepipeline.Pipeline;
+declare const anotherStage: codepipeline.IStage;
+declare const yetAnotherStage: codepipeline.IStage;
+
 const someStage = pipeline.addStage({
   stageName: 'SomeStage',
   placement: {
     // note: you can only specify one of the below properties
     rightBefore: anotherStage,
-    justAfter: anotherStage
+    justAfter: yetAnotherStage,
   }
 });
 ```
@@ -106,6 +116,9 @@ in the `actions` property,
 or you can use the `IStage.addAction()` method to mutate an existing Stage:
 
 ```ts
+// Use the `IStage.addAction()` method to mutate an existing Stage.
+declare const sourceStage: codepipeline.IStage;
+declare const someAction: codepipeline.Action;
 sourceStage.addAction(someAction);
 ```
 
@@ -114,6 +127,7 @@ sourceStage.addAction(someAction);
 To make your own custom CodePipeline Action requires registering the action provider. Look to the `JenkinsProvider` in `@aws-cdk/aws-codepipeline-actions` for an implementation example.
 
 ```ts
+// Make a custom CodePipeline Action
 new codepipeline.CustomActionRegistration(this, 'GenericGitSourceProviderResource', {
   category: codepipeline.ActionCategory.SOURCE,
   artifactBounds: { minInputs: 0, maxInputs: 0, minOutputs: 1, maxOutputs: 1 },
@@ -140,7 +154,8 @@ new codepipeline.CustomActionRegistration(this, 'GenericGitSourceProviderResourc
       description: 'SSH git clone URL',
       type: 'String',
     },
-  ]
+  ],
+});
 ```
 
 ## Cross-account CodePipelines
@@ -163,20 +178,32 @@ example, the following action deploys to an imported S3 bucket from a
 different account:
 
 ```ts
+// Deploy an imported S3 bucket from a different account
+declare const stage: codepipeline.IStage;
+declare const input: codepipeline.Artifact;
 stage.addAction(new codepipeline_actions.S3DeployAction({
   bucket: s3.Bucket.fromBucketAttributes(this, 'Bucket', {
     account: '123456789012',
     // ...
   }),
+  input: input,
+  actionName: 's3-deploy-action',
   // ...
 }));
 ```
 
 Actions that don't accept a resource object accept an explicit `account` parameter:
 
 ```ts
+// Actions that don't accept a resource objet accept an explicit `account` parameter
+declare const stage: codepipeline.IStage;
+declare const templatePath: codepipeline.ArtifactPath;
 stage.addAction(new codepipeline_actions.CloudFormationCreateUpdateStackAction({
   account: '123456789012',
+  templatePath,
+  adminPermissions: false,
+  stackName: Stack.of(this).stackName,
+  actionName: 'cloudformation-create-update',
   // ...
 }));
 ```
@@ -192,7 +219,14 @@ If you do not want to use the generated role, you can also explicitly pass a
 account the role belongs to:
 
 ```ts
+// Explicitly pass in a `role` when creating an action.
+declare const stage: codepipeline.IStage;
+declare const templatePath: codepipeline.ArtifactPath;
 stage.addAction(new codepipeline_actions.CloudFormationCreateUpdateStackAction({
+  templatePath,
+  adminPermissions: false,
+  stackName: Stack.of(this).stackName,
+  actionName: 'cloudformation-create-update',
   // ...
   role: iam.Role.fromRoleArn(this, 'ActionRole', '...'),
 }));
@@ -205,11 +239,16 @@ pass to actions can also be in different *Regions*. For example, the
 following Action deploys to an imported S3 bucket from a different Region:
 
 ```ts
+// Deploy to an imported S3 bucket from a different Region.
+declare const stage: codepipeline.IStage;
+declare const input: codepipeline.Artifact;
 stage.addAction(new codepipeline_actions.S3DeployAction({
   bucket: s3.Bucket.fromBucketAttributes(this, 'Bucket', {
     region: 'us-west-1',
     // ...
   }),
+  input: input,
+  actionName: 's3-deploy-action',
   // ...
 }));
 ```
@@ -218,7 +257,14 @@ Actions that don't take an AWS resource will accept an explicit `region`
 parameter:
 
 ```ts
+// Actions that don't take an AWS resource will accept an explicit `region` parameter.
+declare const stage: codepipeline.IStage;
+declare const templatePath: codepipeline.ArtifactPath;
 stage.addAction(new codepipeline_actions.CloudFormationCreateUpdateStackAction({
+  templatePath,
+  adminPermissions: false,
+  stackName: Stack.of(this).stackName,
+  actionName: 'cloudformation-create-update',
   // ...
   region: 'us-west-1',
 }));
@@ -235,6 +281,7 @@ place to serve as replication buckets, you can supply these at Pipeline definiti
 time using the `crossRegionReplicationBuckets` parameter. Example:
 
 ```ts
+// Supply replication buckets for the Pipeline instead of using the generated support stack
 const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
   // ...
 
@@ -260,6 +307,8 @@ If you're passing a replication bucket created in a different stack,
 like this:
 
 ```ts
+// Passing a replication bucket created in a different stack.
+const app = new App();
 const replicationStack = new Stack(app, 'ReplicationStack', {
   env: {
     region: 'us-west-1',
@@ -273,7 +322,7 @@ const replicationBucket = new s3.Bucket(replicationStack, 'ReplicationBucket', {
 });
 
 // later...
-new codepipeline.Pipeline(pipelineStack, 'Pipeline', {
+new codepipeline.Pipeline(replicationStack, 'Pipeline', {
   crossRegionReplicationBuckets: {
     'us-west-1': replicationBucket,
   },
@@ -289,6 +338,13 @@ and so you can't reference them across environments.
 In this case, you need to use an alias in place of the key when creating the bucket:
 
 ```ts
+// Passing an encrypted replication bucket created in a different stack.
+const app = new App();
+const replicationStack = new Stack(app, 'ReplicationStack', {
+  env: {
+    region: 'us-west-1',
+  },
+});
 const key = new kms.Key(replicationStack, 'ReplicationKey');
 const alias = new kms.Alias(replicationStack, 'ReplicationAlias', {
   // aliasName is required
@@ -312,36 +368,42 @@ you access the appropriate property of the interface returned from `variables`,
 which represents a single variable.
 Example:
 
-```ts
-// MyAction is some action type that produces variables
+```ts fixture=action
+// MyAction is some action type that produces variables, like EcrSourceAction
 const myAction = new MyAction({
   // ...
+  actionName: 'myAction',
 });
 new OtherAction({
   // ...
   config: myAction.variables.myVariable,
+  actionName: 'otherAction',
 });
 ```
 
 The namespace name that will be used will be automatically generated by the pipeline construct,
 based on the stage and action name;
 you can pass a custom name when creating the action instance:
 
-```ts
+```ts fixture=action
+// MyAction is some action type that produces variables, like EcrSourceAction
 const myAction = new MyAction({
   // ...
   variablesNamespace: 'MyNamespace',
+  actionName: 'myAction',
 });
 ```
 
 There are also global variables available,
 not tied to any action;
 these are accessed through static properties of the `GlobalVariables` class:
 
-```ts
+```ts fixture=action
+// OtherAction is some action type that produces variables, like EcrSourceAction
 new OtherAction({
   // ...
   config: codepipeline.GlobalVariables.executionId,
+  actionName: 'otherAction',
 });
 ```
 
@@ -358,6 +420,7 @@ for more details on how to use the variables feature.
 A pipeline can be used as a target for a CloudWatch event rule:
 
 ```ts
+// A pipeline being used as a target for a CloudWatch event rule.
 import * as targets from '@aws-cdk/aws-events-targets';
 import * as events from '@aws-cdk/aws-events';
 
@@ -366,6 +429,7 @@ const rule = new events.Rule(this, 'Daily', {
   schedule: events.Schedule.rate(Duration.days(1)),
 });
 
+declare const pipeline: codepipeline.Pipeline;
 rule.addTarget(new targets.CodePipeline(pipeline));
 ```
 
@@ -380,7 +444,14 @@ the pipeline, stages or action, use the `onXxx` methods on the respective
 construct:
 
 ```ts
-myPipeline.onStateChange('MyPipelineStateChange', target);
+// Define event rules for events emitted by the pipeline
+import * as events from '@aws-cdk/aws-events';
+
+declare const myPipeline: codepipeline.Pipeline;
+declare const myStage: codepipeline.IStage;
+declare const myAction: codepipeline.Action;
+declare const target: events.IRuleTarget;
+myPipeline.onStateChange('MyPipelineStateChange', { target: target } );
 myStage.onStateChange('MyStageStateChange', target);
 myAction.onStateChange('MyActionStateChange', target);
 ```
@@ -391,11 +462,14 @@ To define CodeStar Notification rules for Pipelines, use one of the `notifyOnXxx
 They are very similar to `onXxx()` methods for CloudWatch events:
 
 ```ts
-const target = new chatbot.SlackChannelConfiguration(stack, 'MySlackChannel', {
+// Define CodeStar Notification rules for Pipelines
+import * as chatbot from '@aws-cdk/aws-chatbot';
+const target = new chatbot.SlackChannelConfiguration(this, 'MySlackChannel', {
   slackChannelConfigurationName: 'YOUR_CHANNEL_NAME',
   slackWorkspaceId: 'YOUR_SLACK_WORKSPACE_ID',
   slackChannelId: 'YOUR_SLACK_CHANNEL_ID',
 });
 
+declare const pipeline: codepipeline.Pipeline;
 const rule = pipeline.notifyOnExecutionStateChange('NotifyOnExecutionStateChange', target);
 ```

packages/@aws-cdk/aws-codepipeline/lib/custom-action-registration.ts

@@ -79,7 +79,7 @@ export interface CustomActionRegistrationProps {
 
   /**
    * The provider of the Action.
-   * @example 'MyCustomActionProvider'
+   * For example, `'MyCustomActionProvider'`
    */
   readonly provider: string;
 

packages/@aws-cdk/aws-codepipeline/lib/pipeline.ts

@@ -263,15 +263,19 @@ abstract class PipelineBase extends Resource implements IPipeline {
  *
  * @example
  * // create a pipeline
- * const pipeline = new Pipeline(this, 'Pipeline');
+ * import * as codecommit from '@aws-cdk/aws-codecommit';
+ *
+ * const pipeline = new codepipeline.Pipeline(this, 'Pipeline');
  *
  * // add a stage
  * const sourceStage = pipeline.addStage({ stageName: 'Source' });
  *
  * // add a source action to the stage
+ * declare const repo: codecommit.Repository;
+ * declare const sourceArtifact: codepipeline.Artifact;
  * sourceStage.addAction(new codepipeline_actions.CodeCommitSourceAction({
  *   actionName: 'Source',
- *   outputArtifactName: 'SourceArtifact',
+ *   output: sourceArtifact,
  *   repository: repo,
  * }));
  *

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

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