From ec0ecb7761691866960b9128502f6db127871439 Mon Sep 17 00:00:00 2001
From: Rico Huijbers <rix0rrr@gmail.com>
Date: Mon, 6 Jan 2020 14:59:39 +0100
Subject: [PATCH] docs(ec2): improve SecurityGroup documentation

For people already familiar with the inner workings of Security Groups,
our `.connections` pattern is a little confusing.

Add some more verbiage to the documentation which points people in
the right direction with respect to security group manipulation.

Closes #5519.
---
 packages/@aws-cdk/aws-ec2/lib/peer.ts         | 12 +++++-
 .../@aws-cdk/aws-ec2/lib/security-group.ts    | 38 +++++++++++++++++--
 2 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/packages/@aws-cdk/aws-ec2/lib/peer.ts b/packages/@aws-cdk/aws-ec2/lib/peer.ts
index 0af091cb7b890..bef1c90b11ed4 100644
--- a/packages/@aws-cdk/aws-ec2/lib/peer.ts
+++ b/packages/@aws-cdk/aws-ec2/lib/peer.ts
@@ -27,7 +27,17 @@ export interface IPeer extends IConnectable {
 }
 
 /**
- * Factories for static connection peer
+ * Peer object factories (to be used in Security Group management)
+ *
+ * The static methods on this object can be used to create peer objects
+ * which represent a connection partner in Security Group rules.
+ *
+ * Use this object if you need to represent connection partners using plain IP
+ * addresses, or a prefix list ID.
+ *
+ * If you want to address a connection partner by Security Group, you can just
+ * use the Security Group (or the construct that contains a Security Group)
+ * directly, as it already implements `IPeer`.
  */
 export class Peer {
   /**
diff --git a/packages/@aws-cdk/aws-ec2/lib/security-group.ts b/packages/@aws-cdk/aws-ec2/lib/security-group.ts
index 48179656f64f2..1373c811df30b 100644
--- a/packages/@aws-cdk/aws-ec2/lib/security-group.ts
+++ b/packages/@aws-cdk/aws-ec2/lib/security-group.ts
@@ -7,6 +7,9 @@ import { IVpc } from './vpc';
 
 const SECURITY_GROUP_SYMBOL = Symbol.for('@aws-cdk/iam.SecurityGroup');
 
+/**
+ * Interface for security group-like objects
+ */
 export interface ISecurityGroup extends IResource, IPeer {
   /**
    * ID for the current security group
@@ -250,9 +253,38 @@ export interface SecurityGroupImportOptions {
 /**
  * Creates an Amazon EC2 security group within a VPC.
  *
- * This class has an additional optimization over imported security groups that it can also create
- * inline ingress and egress rule (which saves on the total number of resources inside
- * the template).
+ * Security Groups act like a firewall with a set of rules, and are associated
+ * with any AWS resource that has or creates Elastic Network Interfaces (ENIs).
+ * A typical example of a resource that has a security group is an Instance (or
+ * Auto Scaling Group of instances)
+ *
+ * If you are defining new infrastructure in CDK, there is a good chance you
+ * won't have to interact with this class at all. Like IAM Roles, Security
+ * Groups need to exist to control access between AWS resources, but CDK will
+ * automatically generate and populate them with least-privilege permissions
+ * for you so you can concentrate on your business logic.
+ *
+ * All Constructs that require Security Groups will create one for you if you
+ * don't specify one at construction. After construction, you can selectively
+ * allow connections to and between constructs via--for example-- the `instance.connections`
+ * object. Think of it as "allowing connections to your instance", rather than
+ * "adding ingress rules a security group". See the [Allowing
+ * Connections](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-ec2-readme.html#allowing-connections)
+ * section in the library documentation for examples.
+ *
+ * Direct manipulation of the Security Group through `addIngressRule` and
+ * `addEgressRule` is possible, but mutation through the `.connections` object
+ * is recommended. If you peer two constructs with security groups this way,
+ * appropriate rules will be created in both.
+ *
+ * If you have an existing security group you want to use in your CDK application,
+ * you would import it like this:
+ *
+ * ```ts
+ * const securityGroup = SecurityGroup.fromSecurityGroupId(this, 'SG', 'sg-12345', {
+ *   mutable: false
+ * });
+ * ```
  */
 export class SecurityGroup extends SecurityGroupBase {