chore(certificatemanager): Update README to inline examples and menti…

…on limits (aws#9800)

Minor refactoring of the README to inline the examples (from the `.lit.ts`
files), and to explicitly call out the yearly certificate limit.

fixes aws#5889

----

*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-certificatemanager/README.md

@@ -1,4 +1,5 @@
 ## AWS Certificate Manager Construct Library
+
 <!--BEGIN STABILITY BANNER-->
 ---
 
@@ -9,12 +10,11 @@
 ---
 <!--END STABILITY BANNER-->
 
-This package provides Constructs for provisioning and referencing
-certificates which can be used in CloudFront and ELB.
-
-The following requests a certificate for a given domain:
+AWS Certificate Manager (ACM) handles the complexity of creating, storing, and renewing public and private SSL/TLS X.509 certificates and keys that
+protect your AWS websites and applications. ACM certificates can secure singular domain names, multiple specific domain names, wildcard domains, or
+combinations of these. ACM wildcard certificates can protect an unlimited number of subdomains.
 
-[request a certificate example](test/example.simple-request.lit.ts)
+This package provides Constructs for provisioning and referencing ACM certificates which can be used with CloudFront and ELB.
 
 After requesting a certificate, you will need to prove that you own the
 domain in question before the certificate will be granted. The CloudFormation
@@ -24,67 +24,99 @@ Because of this wait time, when using manual validation methods, it's better
 to provision your certificates either in a separate stack from your main
 service, or provision them manually and import them into your CDK application.
 
-### Email validation
+**Note:** There is a limit on total number of ACM certificates that can be requested on an account and region within a year.
+The default limit is 2000, but this limit may be (much) lower on new AWS accounts.
+See https://docs.aws.amazon.com/acm/latest/userguide/acm-limits.html for more information.
 
-Email-validated certificates (the default) are validated by receiving an
-email on one of a number of predefined domains and following the instructions
-in the email.
+### DNS validation
 
-See [Validate with Email](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-validate-email.html)
+DNS validation is the preferred method to validate domain ownership, as it has a number of advantages over email validation.
+See also [Validate with DNS](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-validate-dns.html)
 in the AWS Certificate Manager User Guide.
 
-### DNS validation
-
 If Amazon Route 53 is your DNS provider for the requested domain, the DNS record can be
 created automatically:
 
 ```ts
-new Certificate(this, 'Certificate', {
+import * as acm from '@aws-cdk/aws-certificatemanager';
+import * as route53 from '@aws-cdk/aws-route53';
+
+const myHostedZone = new route53.HostedZone(this, 'HostedZone', {
+  zoneName: 'example.com',
+});
+new acm.Certificate(this, 'Certificate', {
   domainName: 'hello.example.com',
-  validation: CertificateValidation.fromDns(myHostedZone), // Route 53 hosted zone
+  validation: acm.CertificateValidation.fromDns(myHostedZone),
 });
 ```
 
-Otherwise DNS records must be added manually and the stack will not complete
+If Route 53 is not your DNS provider, the DNS records must be added manually and the stack will not complete
 creating until the records are added.
 
 ```ts
-new Certificate(this, 'Certificate', {
+new acm.Certificate(this, 'Certificate', {
   domainName: 'hello.example.com',
-  validation: CertificateValidation.fromDns(), // Records must be added manually
+  validation: acm.CertificateValidation.fromDns(), // Records must be added manually
 });
 ```
 
-See also [Validate with DNS](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-validate-dns.html)
-in the AWS Certificate Manager User Guide.
-
 When working with multiple domains, use the `CertificateValidation.fromDnsMultiZone()`:
 
-[multiple domains DNS validation](test/example.dns.lit.ts)
+```ts
+const exampleCom = new route53.HostedZone(this, 'ExampleCom', {
+  zoneName: 'example.com',
+});
+const exampleNet = new route53.HostedZone(this, 'ExampelNet', {
+  zoneName: 'example.net',
+});
+
+const cert = new acm.Certificate(this, 'Certificate', {
+  domainName: 'test.example.com',
+  subjectAlternativeNames: ['cool.example.com', 'test.example.net'],
+  validation: acm.CertificateValidation.fromDnsMultiZone({
+    'text.example.com': exampleCom,
+    'cool.example.com': exampleCom,
+    'test.example.net': exampleNet,
+  }),
+});
+```
+
+### Email validation
 
-Use the `DnsValidatedCertificate` construct for cross-region certificate creation:
+Email-validated certificates (the default) are validated by receiving an
+email on one of a number of predefined domains and following the instructions
+in the email.
+
+See [Validate with Email](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-validate-email.html)
+in the AWS Certificate Manager User Guide.
 
 ```ts
-new DnsValidatedCertificate(this, 'CrossRegionCertificate', {
+new acm.Certificate(this, 'Certificate', {
   domainName: 'hello.example.com',
-  hostedZone: myHostedZone,
-  region: 'us-east-1',
+  validation: acm.CertificateValidation.fromEmail(), // Optional, this is the default
 });
 ```
 
-This is useful when deploying a stack in a region other than `us-east-1` with a
-certificate for a CloudFront distribution.
+### Cross-region Certificates
 
-If cross-region is not needed, the recommended solution is to use the
-`Certificate` construct which uses a native CloudFormation implementation.
+ACM certificates that are used with CloudFront -- or higher-level constructs which rely on CloudFront -- must be in the `us-east-1` region.
+The `DnsValidatedCertificate` construct exists to faciliate creating these certificates cross-region. This resource can only be used with
+Route53-based DNS validation.
 
+```ts
+new acm.DnsValidatedCertificate(this, 'CrossRegionCertificate', {
+  domainName: 'hello.example.com',
+  hostedZone: myHostedZone,
+  region: 'us-east-1',
+});
+```
 
 ### Importing
 
 If you want to import an existing certificate, you can do so from its ARN:
 
 ```ts
-const arn = "arn:aws:...";
+const arn = 'arn:aws:...';
 const certificate = Certificate.fromCertificateArn(this, 'Certificate', arn);
 ```