docs(ec2): improve SecurityGroup documentation

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 {
   /**

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 {