From 3b7afce52d6039a16e8c9d231df0b5bb0a36cd4d Mon Sep 17 00:00:00 2001
From: Adam Ruka <adamruka85@gmail.com>
Date: Fri, 21 Jan 2022 15:29:32 -0800
Subject: [PATCH] Applu doc wording suggestions

---
 .../@aws-cdk/aws-codepipeline-actions/README.md  | 16 ++++++++++------
 .../@aws-cdk/aws-ecs/lib/base/base-service.ts    |  4 ++--
 packages/@aws-cdk/aws-ecs/lib/cluster.ts         |  4 ++--
 3 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/packages/@aws-cdk/aws-codepipeline-actions/README.md b/packages/@aws-cdk/aws-codepipeline-actions/README.md
index 4e16e1d0bb9b8..ff43850561651 100644
--- a/packages/@aws-cdk/aws-codepipeline-actions/README.md
+++ b/packages/@aws-cdk/aws-codepipeline-actions/README.md
@@ -764,9 +764,11 @@ const deployStage = pipeline.addStage({
 
 [image definition file]: https://docs.aws.amazon.com/codepipeline/latest/userguide/pipelines-create.html#pipelines-create-image-definitions
 
-#### Deploying ECS applications with existing ECS service ARN
+#### Deploying ECS applications to existing services
 
-CodePipeline can deploy an ECS service which [cluster formatted ECS service ARN](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-account-settings.html#ecs-resource-ids) this can be deploy across region and accounts as well using the ARN.
+CodePipeline can deploy to an existing ECS service which uses the
+[ECS service ARN format that contains the Cluster name](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-account-settings.html#ecs-resource-ids).
+This also works if the service is in a different account and/or region than the pipeline:
 
 ```ts
 import * as ecs from '@aws-cdk/aws-ecs';
@@ -776,6 +778,7 @@ const service = ecs.BaseService.fromServiceArnWithCluster(this, 'EcsService',
 );
 const pipeline = new codepipeline.Pipeline(this, 'MyPipeline');
 const buildOutput = new codepipeline.Artifact();
+// add source and build stages to the pipeline as usual...
 const deployStage = pipeline.addStage({
   stageName: 'Deploy',
   actions: [
@@ -788,10 +791,11 @@ const deployStage = pipeline.addStage({
 });
 ```
 
-When deploying across accounts especially in a CDK self mutating pipeline it is recommended to provide
-the `role` on the `EcsDeployAction`.  The role will need to have permissions assigned to it for
-ECS deployment see [EcsDeployAction](https://github.com/aws/aws-cdk/blob/d735ce4bc9049b68b830641d68c97f4be565968d/packages/%40aws-cdk/aws-codepipeline-actions/lib/ecs/deploy-action.ts#L85-L110) for proper permissions to apply to the role.
-
+When deploying across accounts, especially in a CDK Pipelines self-mutating pipeline,
+it is recommended to provide the `role` property to the `EcsDeployAction`. 
+The Role will need to have permissions assigned to it for ECS deployment.
+See [the CodePipeline documentation](https://docs.aws.amazon.com/codepipeline/latest/userguide/how-to-custom-role.html#how-to-update-role-new-services)
+for the permissions needed.
 
 #### Deploying ECS applications stored in a separate source code repository
 
diff --git a/packages/@aws-cdk/aws-ecs/lib/base/base-service.ts b/packages/@aws-cdk/aws-ecs/lib/base/base-service.ts
index df8b18b383ba4..4e5de4c90eacf 100644
--- a/packages/@aws-cdk/aws-ecs/lib/base/base-service.ts
+++ b/packages/@aws-cdk/aws-ecs/lib/base/base-service.ts
@@ -317,8 +317,8 @@ export abstract class BaseService extends Resource
   implements IBaseService, elbv2.IApplicationLoadBalancerTarget, elbv2.INetworkLoadBalancerTarget, elb.ILoadBalancerTarget {
   /**
    * Import an existing ECS/Fargate Service using the service cluster format.
-   * The format is the "new" format "arn:aws:ecs:region:aws_account_id:service/cluster-name/service-name"
-   * see https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-account-settings.html#ecs-resource-ids
+   * The format is the "new" format "arn:aws:ecs:region:aws_account_id:service/cluster-name/service-name".
+   * @see https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-account-settings.html#ecs-resource-ids
    */
   public static fromServiceArnWithCluster(scope: Construct, id: string, serviceArn: string): IBaseService {
     const stack = Stack.of(scope);
diff --git a/packages/@aws-cdk/aws-ecs/lib/cluster.ts b/packages/@aws-cdk/aws-ecs/lib/cluster.ts
index 23116a6e1e215..8e48e2be59cec 100644
--- a/packages/@aws-cdk/aws-ecs/lib/cluster.ts
+++ b/packages/@aws-cdk/aws-ecs/lib/cluster.ts
@@ -107,8 +107,8 @@ export class Cluster extends Resource implements ICluster {
 
   /**
    * Import an existing cluster to the stack from the cluster ARN.
-   * This does not provide access to the vpc, hasEc2Capacity, or connections use fromClusterAttributes to
-   * access those properties.
+   * This does not provide access to the vpc, hasEc2Capacity, or connections -
+   * use the `fromClusterAttributes` method to access those properties.
    */
   public static fromClusterArn(scope: Construct, id: string, clusterArn: string): ICluster {
     const stack = Stack.of(scope);