From 80f72c7199e999e087a189fa4c2195e33ddd5242 Mon Sep 17 00:00:00 2001
From: shivlaks <32604953+shivlaks@users.noreply.github.com>
Date: Thu, 23 May 2019 02:44:22 -0700
Subject: [PATCH] refactor: L2 constructs should include default docs for
 optional props (awslint:props-default-doc) (#2611)

Adds a new awslint:props-default-doc rule which verifies that optional props have default value/behavior documented.

This is in accordance with the new AWS Construct Library guidelines.

Fixes #2432
---
 packages/@aws-cdk/assets/lib/asset.ts         |  6 +++
 .../@aws-cdk/aws-apigateway/lib/deployment.ts |  2 +
 .../@aws-cdk/aws-apigateway/lib/method.ts     |  6 ++-
 .../@aws-cdk/aws-apigateway/lib/resource.ts   |  4 ++
 .../@aws-cdk/aws-apigateway/lib/restapi.ts    | 23 +++++++---
 packages/@aws-cdk/aws-apigateway/lib/stage.ts | 33 +++++++++++++--
 .../lib/target-tracking-scaling-policy.ts     | 12 ++++--
 .../aws-autoscaling/lib/auto-scaling-group.ts | 15 +++++--
 .../aws-autoscaling/lib/lifecycle-hook.ts     |  8 ++--
 .../aws-autoscaling/lib/scheduled-action.ts   | 10 +++--
 .../lib/target-tracking-scaling-policy.ts     | 10 +++--
 .../aws-certificatemanager/lib/certificate.ts |  4 +-
 .../aws-cloudformation/lib/custom-resource.ts |  4 ++
 .../aws-cloudfront/lib/web_distribution.ts    | 42 ++++++++++++-------
 packages/@aws-cdk/aws-cloudtrail/lib/index.ts | 20 ++++++---
 .../@aws-cdk/aws-cloudwatch/lib/metric.ts     |  6 ++-
 .../@aws-cdk/aws-codebuild/lib/project.ts     | 35 ++++++++++++----
 .../@aws-cdk/aws-codecommit/lib/repository.ts |  2 +
 .../lib/lambda/deployment-group.ts            | 12 ++++--
 .../lib/server/deployment-group.ts            | 16 ++++---
 .../lib/jenkins/jenkins-provider.ts           |  4 ++
 .../@aws-cdk/aws-codepipeline/lib/pipeline.ts | 14 +++++--
 .../@aws-cdk/aws-cognito/lib/user-pool.ts     | 14 +++++--
 packages/@aws-cdk/aws-ec2/lib/vpc.ts          | 28 +++++++++----
 .../@aws-cdk/aws-ecs/lib/base/base-service.ts |  8 ++--
 .../aws-ecs/lib/base/task-definition.ts       | 23 ++++++++--
 .../aws-ecs/lib/container-definition.ts       | 31 +++++++++-----
 .../@aws-cdk/aws-ecs/lib/ec2/ec2-service.ts   |  8 ++--
 .../aws-ecs/lib/ec2/ec2-task-definition.ts    |  4 +-
 .../aws-ecs/lib/fargate/fargate-service.ts    |  6 +--
 .../@aws-cdk/aws-ecs/lib/linux-parameters.ts  |  4 ++
 .../aws-ecs/lib/load-balanced-ecs-service.ts  |  4 ++
 .../load-balanced-fargate-service-applet.ts   | 10 ++++-
 .../lib/load-balanced-fargate-service.ts      |  6 ++-
 .../aws-ecs/lib/load-balanced-service-base.ts |  5 ++-
 .../aws-ecs/lib/log-drivers/aws-log-driver.ts | 10 ++++-
 .../lib/load-balancer.ts                      |  6 +++
 .../lib/alb/application-listener-rule.ts      |  8 +++-
 .../lib/alb/application-listener.ts           | 10 +++--
 .../lib/alb/application-target-group.ts       |  6 ++-
 .../lib/nlb/network-listener.ts               |  8 +++-
 .../lib/nlb/network-target-group.ts           |  2 +
 .../lib/shared/base-load-balancer.ts          |  4 +-
 .../lib/shared/base-target-group.ts           |  6 +--
 packages/@aws-cdk/aws-events/lib/rule.ts      | 18 ++++++--
 packages/@aws-cdk/aws-iam/lib/group.ts        |  5 ++-
 packages/@aws-cdk/aws-iam/lib/policy.ts       | 12 +++++-
 packages/@aws-cdk/aws-iam/lib/role.ts         | 22 ++++++----
 packages/@aws-cdk/aws-iam/lib/user.ts         |  7 +++-
 packages/@aws-cdk/aws-kms/lib/key.ts          |  8 +++-
 .../aws-lambda/lib/event-source-mapping.ts    |  4 +-
 packages/@aws-cdk/aws-lambda/lib/function.ts  | 39 ++++++++++-------
 packages/@aws-cdk/aws-lambda/lib/layers.ts    | 13 ++++--
 .../@aws-cdk/aws-quickstarts/package.json     |  5 +++
 .../aws-rds/lib/cluster-parameter-group.ts    |  2 +
 packages/@aws-cdk/aws-rds/lib/cluster.ts      | 26 ++++++++----
 packages/@aws-cdk/aws-rds/lib/props.ts        |  5 +++
 .../aws-rds/lib/rotation-single-user.ts       |  4 +-
 packages/@aws-cdk/aws-s3/lib/bucket.ts        | 23 +++++++---
 .../@aws-cdk/aws-secretsmanager/lib/secret.ts | 10 +++--
 .../@aws-cdk/aws-ses/lib/receipt-rule-set.ts  |  4 +-
 packages/@aws-cdk/aws-ses/lib/receipt-rule.ts | 15 ++++---
 packages/@aws-cdk/cdk/lib/cfn-condition.ts    |  5 +++
 packages/@aws-cdk/cdk/lib/cfn-mapping.ts      | 10 +++++
 packages/@aws-cdk/cdk/lib/cfn-output.ts       | 10 ++++-
 packages/@aws-cdk/cdk/lib/cfn-parameter.ts    | 20 +++++++++
 packages/@aws-cdk/cdk/lib/cfn-resource.ts     |  2 +
 packages/@aws-cdk/cdk/lib/cfn-rule.ts         |  4 ++
 packages/@aws-cdk/cdk/lib/stack.ts            |  6 +--
 tools/awslint/lib/rules/construct.ts          | 19 ++++++++-
 70 files changed, 600 insertions(+), 197 deletions(-)

diff --git a/packages/@aws-cdk/assets/lib/asset.ts b/packages/@aws-cdk/assets/lib/asset.ts
index f725e857cd84c..26aa2ae915c59 100644
--- a/packages/@aws-cdk/assets/lib/asset.ts
+++ b/packages/@aws-cdk/assets/lib/asset.ts
@@ -36,6 +36,8 @@ export interface AssetProps {
   /**
    * A list of principals that should be able to read this asset from S3.
    * You can use `asset.grantRead(principal)` to grant read permissions later.
+   *
+   * @default - No principals that can read file asset.
    */
   readonly readers?: iam.IGrantable[];
 }
@@ -195,6 +197,8 @@ export interface FileAssetProps {
   /**
    * A list of principals that should be able to read this file asset from S3.
    * You can use `asset.grantRead(principal)` to grant read permissions later.
+   *
+   * @default - No principals that can read file asset.
    */
   readonly readers?: iam.IGrantable[];
 }
@@ -217,6 +221,8 @@ export interface ZipDirectoryAssetProps {
   /**
    * A list of principals that should be able to read this ZIP file from S3.
    * You can use `asset.grantRead(principal)` to grant read permissions later.
+   *
+   * @default - No principals that can read file asset.
    */
   readonly readers?: iam.IGrantable[];
 }
diff --git a/packages/@aws-cdk/aws-apigateway/lib/deployment.ts b/packages/@aws-cdk/aws-apigateway/lib/deployment.ts
index 7db0158d2b499..6cafaeca0d833 100644
--- a/packages/@aws-cdk/aws-apigateway/lib/deployment.ts
+++ b/packages/@aws-cdk/aws-apigateway/lib/deployment.ts
@@ -11,6 +11,8 @@ export interface DeploymentProps  {
 
   /**
    * A description of the purpose of the API Gateway deployment.
+   *
+   * @default - No description.
    */
   readonly description?: string;
 
diff --git a/packages/@aws-cdk/aws-apigateway/lib/method.ts b/packages/@aws-cdk/aws-apigateway/lib/method.ts
index c0772c38b6413..bd8a1a41c011f 100644
--- a/packages/@aws-cdk/aws-apigateway/lib/method.ts
+++ b/packages/@aws-cdk/aws-apigateway/lib/method.ts
@@ -75,11 +75,15 @@ export interface MethodProps {
 
   /**
    * The backend system that the method calls when it receives a request.
+   *
+   * @default - a new `MockIntegration`.
    */
   readonly integration?: Integration;
 
   /**
    * Method options.
+   *
+   * @default - No options.
    */
   readonly options?: MethodOptions;
 }
@@ -101,7 +105,7 @@ export class Method extends Resource {
 
     validateHttpMethod(this.httpMethod);
 
-    const options = props.options || { };
+    const options = props.options || {};
 
     const defaultMethodOptions = props.resource.defaultMethodOptions || {};
 
diff --git a/packages/@aws-cdk/aws-apigateway/lib/resource.ts b/packages/@aws-cdk/aws-apigateway/lib/resource.ts
index 20a9ab49b97cc..6bf890eb5a60d 100644
--- a/packages/@aws-cdk/aws-apigateway/lib/resource.ts
+++ b/packages/@aws-cdk/aws-apigateway/lib/resource.ts
@@ -91,12 +91,16 @@ export interface ResourceOptions {
   /**
    * An integration to use as a default for all methods created within this
    * API unless an integration is specified.
+   *
+   * @default - Inherited from parent.
    */
   readonly defaultIntegration?: Integration;
 
   /**
    * Method options to use as a default for all methods created within this
    * API unless custom options are specified.
+   *
+   * @default - Inherited from parent.
    */
   readonly defaultMethodOptions?: MethodOptions;
 }
diff --git a/packages/@aws-cdk/aws-apigateway/lib/restapi.ts b/packages/@aws-cdk/aws-apigateway/lib/restapi.ts
index 47e869e66dcd3..a274d3e346802 100644
--- a/packages/@aws-cdk/aws-apigateway/lib/restapi.ts
+++ b/packages/@aws-cdk/aws-apigateway/lib/restapi.ts
@@ -44,7 +44,7 @@ export interface RestApiProps extends ResourceOptions {
    * deployment when `deploy` is enabled. If `deploy` is disabled,
    * this value cannot be set.
    *
-   * @default defaults based on defaults of `StageOptions`
+   * @default - Based on defaults of `StageOptions`.
    */
   readonly deployOptions?: StageOptions;
 
@@ -60,31 +60,37 @@ export interface RestApiProps extends ResourceOptions {
   /**
    * A name for the API Gateway RestApi resource.
    *
-   * @default construct-id defaults to the id of the RestApi construct
+   * @default - ID of the RestApi construct.
    */
   readonly restApiName?: string;
 
   /**
    * Custom header parameters for the request.
    * @see https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html
+   *
+   * @default - No parameters.
    */
   readonly parameters?: { [key: string]: string };
 
   /**
    * A policy document that contains the permissions for this RestApi
+   *
+   * @default - No policy.
    */
   readonly policy?: iam.PolicyDocument;
 
   /**
    * A description of the purpose of this API Gateway RestApi resource.
-   * @default No description
+   *
+   * @default - No description.
    */
   readonly description?: string;
 
   /**
    * The source of the API key for metering requests according to a usage
    * plan.
-   * @default undefined metering is disabled
+   *
+   * @default - Metering is disabled.
    */
   readonly apiKeySourceType?: ApiKeySourceType;
 
@@ -92,13 +98,15 @@ export interface RestApiProps extends ResourceOptions {
    * The list of binary media mine-types that are supported by the RestApi
    * resource, such as "image/png" or "application/octet-stream"
    *
-   * @default By default, RestApi supports only UTF-8-encoded text payloads
+   * @default - RestApi supports only UTF-8-encoded text payloads.
    */
   readonly binaryMediaTypes?: string[];
 
   /**
    * A list of the endpoint types of the API. Use this property when creating
    * an API.
+   *
+   * @default - No endpoint types.
    */
   readonly endpointTypes?: EndpointType[];
 
@@ -118,17 +126,20 @@ export interface RestApiProps extends ResourceOptions {
    * smaller than this value. Setting it to zero allows compression for any
    * payload size.
    *
-   * @default undefined compression is disabled
+   * @default - Compression is disabled.
    */
   readonly minimumCompressionSize?: number;
 
   /**
    * The ID of the API Gateway RestApi resource that you want to clone.
+   *
+   * @default - None.
    */
   readonly cloneFrom?: IRestApi;
 
   /**
    * Automatically configure an AWS CloudWatch role for API Gateway.
+   *
    * @default true
    */
   readonly cloudWatchRole?: boolean;
diff --git a/packages/@aws-cdk/aws-apigateway/lib/stage.ts b/packages/@aws-cdk/aws-apigateway/lib/stage.ts
index 8825bb866bbba..06c065fbdf1e7 100644
--- a/packages/@aws-cdk/aws-apigateway/lib/stage.ts
+++ b/packages/@aws-cdk/aws-apigateway/lib/stage.ts
@@ -9,18 +9,21 @@ export interface StageOptions extends MethodDeploymentOptions {
    * The name of the stage, which API Gateway uses as the first path segment
    * in the invoked Uniform Resource Identifier (URI).
    *
-   * @default "prod"
+   * @default - "prod"
    */
   readonly stageName?: string;
 
   /**
    * Specifies whether Amazon X-Ray tracing is enabled for this method.
+   *
    * @default false
    */
   readonly tracingEnabled?: boolean;
 
   /**
    * Indicates whether cache clustering is enabled for the stage.
+   *
+   * @default - Disabled for the stage.
    */
   readonly cacheClusterEnabled?: boolean;
 
@@ -34,17 +37,21 @@ export interface StageOptions extends MethodDeploymentOptions {
    * The identifier of the client certificate that API Gateway uses to call
    * your integration endpoints in the stage.
    *
-   * @default None
+   * @default - None.
    */
   readonly clientCertificateId?: string;
 
   /**
    * A description of the purpose of the stage.
+   *
+   * @default - No description.
    */
   readonly description?: string;
 
   /**
    * The version identifier of the API documentation snapshot.
+   *
+   * @default - No documentation version.
    */
   readonly documentationVersion?: string;
 
@@ -52,6 +59,8 @@ export interface StageOptions extends MethodDeploymentOptions {
    * A map that defines the stage variables. Variable names must consist of
    * alphanumeric characters, and the values must match the following regular
    * expression: [A-Za-z0-9-._~:/?#&amp;=,]+.
+   *
+   * @default - No stage variables.
    */
   readonly variables?: { [key: string]: string };
 
@@ -62,8 +71,9 @@ export interface StageOptions extends MethodDeploymentOptions {
    * @param path is {resource_path}/{http_method} (i.e. /api/toys/GET) for an
    * individual method override. You can use `*` for both {resource_path} and {http_method}
    * to define options for all methods/resources.
+   *
+   * @default - Common options will be used.
    */
-
   readonly methodOptions?: { [path: string]: MethodDeploymentOptions };
 }
 
@@ -83,6 +93,7 @@ export enum MethodLoggingLevel {
 export interface MethodDeploymentOptions {
   /**
    * Specifies whether Amazon CloudWatch metrics are enabled for this method.
+   *
    * @default false
    */
   readonly metricsEnabled?: boolean;
@@ -90,43 +101,57 @@ export interface MethodDeploymentOptions {
   /**
    * Specifies the logging level for this method, which effects the log
    * entries pushed to Amazon CloudWatch Logs.
-   * @default Off
+   *
+   * @default - Off
    */
   readonly loggingLevel?: MethodLoggingLevel;
 
   /**
    * Specifies whether data trace logging is enabled for this method, which
    * effects the log entries pushed to Amazon CloudWatch Logs.
+   *
    * @default false
    */
   readonly dataTraceEnabled?: boolean;
 
   /**
    * Specifies the throttling burst limit.
+   * The total rate of all requests in your AWS account is limited to 5,000 requests.
    * @see https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-request-throttling.html
+   *
+   * @default - No additional restriction.
    */
   readonly throttlingBurstLimit?: number;
 
   /**
    * Specifies the throttling rate limit.
+   * The total rate of all requests in your AWS account is limited to 10,000 requests per second (rps).
    * @see https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-request-throttling.html
+   *
+   * @default - No additional restriction.
    */
   readonly throttlingRateLimit?: number;
 
   /**
    * Specifies whether responses should be cached and returned for requests. A
    * cache cluster must be enabled on the stage for responses to be cached.
+   *
+   * @default - Caching is Disabled.
    */
   readonly cachingEnabled?: boolean;
 
   /**
    * Specifies the time to live (TTL), in seconds, for cached responses. The
    * higher the TTL, the longer the response will be cached.
+   * @see https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-caching.html
+   *
+   * @default 300
    */
   readonly cacheTtlSeconds?: number;
 
   /**
    * Indicates whether the cached responses are encrypted.
+   *
    * @default false
    */
   readonly cacheDataEncrypted?: boolean;
diff --git a/packages/@aws-cdk/aws-applicationautoscaling/lib/target-tracking-scaling-policy.ts b/packages/@aws-cdk/aws-applicationautoscaling/lib/target-tracking-scaling-policy.ts
index 0026bd6b833fb..3e5a6733aeef4 100644
--- a/packages/@aws-cdk/aws-applicationautoscaling/lib/target-tracking-scaling-policy.ts
+++ b/packages/@aws-cdk/aws-applicationautoscaling/lib/target-tracking-scaling-policy.ts
@@ -16,7 +16,7 @@ export interface BaseTargetTrackingProps {
   /**
    * A name for the scaling policy
    *
-   * @default Automatically generated name
+   * @default - Automatically generated name.
    */
   readonly policyName?: string;
 
@@ -35,14 +35,14 @@ export interface BaseTargetTrackingProps {
   /**
    * Period after a scale in activity completes before another scale in activity can start.
    *
-   * @default No scale in cooldown
+   * @default - No scale in cooldown.
    */
   readonly scaleInCooldownSec?: number;
 
   /**
    * Period after a scale out activity completes before another scale out activity can start.
    *
-   * @default No scale out cooldown
+   * @default - No scale out cooldown.
    */
   readonly scaleOutCooldownSec?: number;
 }
@@ -63,6 +63,8 @@ export interface BasicTargetTrackingScalingPolicyProps extends BaseTargetTrackin
    * the target value, scaling in will happen in the metric is lower than the target value.
    *
    * Exactly one of customMetric or predefinedMetric must be specified.
+   *
+   * @default - No predefined metrics.
    */
   readonly predefinedMetric?: PredefinedMetric;
 
@@ -72,6 +74,8 @@ export interface BasicTargetTrackingScalingPolicyProps extends BaseTargetTrackin
    * Only used for predefined metric ALBRequestCountPerTarget.
    *
    * @example app/<load-balancer-name>/<load-balancer-id>/targetgroup/<target-group-name>/<target-group-id>
+   *
+   * @default - No resource label.
    */
   readonly resourceLabel?: string;
 
@@ -82,6 +86,8 @@ export interface BasicTargetTrackingScalingPolicyProps extends BaseTargetTrackin
    * the target value, scaling in will happen in the metric is lower than the target value.
    *
    * Exactly one of customMetric or predefinedMetric must be specified.
+   *
+   * @default - No custom metric.
    */
   readonly customMetric?: cloudwatch.Metric;
 }
diff --git a/packages/@aws-cdk/aws-autoscaling/lib/auto-scaling-group.ts b/packages/@aws-cdk/aws-autoscaling/lib/auto-scaling-group.ts
index ee85d2bfc4732..238899b972c08 100644
--- a/packages/@aws-cdk/aws-autoscaling/lib/auto-scaling-group.ts
+++ b/packages/@aws-cdk/aws-autoscaling/lib/auto-scaling-group.ts
@@ -40,24 +40,29 @@ export interface CommonAutoScalingGroupProps {
 
   /**
    * Initial amount of instances in the fleet
+   *
    * @default 1
    */
   readonly desiredCapacity?: number;
 
   /**
    * Name of SSH keypair to grant access to instances
-   * @default No SSH access will be possible
+   *
+   * @default - No SSH access will be possible.
    */
   readonly keyName?: string;
 
   /**
    * Where to place instances within the VPC
+   *
+   * @default - All Private subnets.
    */
   readonly vpcSubnets?: ec2.SubnetSelection;
 
   /**
    * SNS topic to send notifications about fleet changes
-   * @default No fleet change notifications will be sent.
+   *
+   * @default - No fleet change notifications will be sent.
    */
   readonly notificationsTopic?: sns.ITopic;
 
@@ -85,6 +90,8 @@ export interface CommonAutoScalingGroupProps {
    * Configuration for rolling updates
    *
    * Only used if updateType == UpdateType.RollingUpdate.
+   *
+   * @default - RollingUpdateConfiguration with defaults.
    */
   readonly rollingUpdateConfiguration?: RollingUpdateConfiguration;
 
@@ -93,6 +100,8 @@ export interface CommonAutoScalingGroupProps {
    *
    * Only used if updateType == UpdateType.ReplacingUpdate. Specifies how
    * many instances must signal success for the update to succeed.
+   *
+   * @default minSuccessfulInstancesPercent
    */
   readonly replacingUpdateMinSuccessfulInstancesPercent?: number;
 
@@ -136,7 +145,7 @@ export interface CommonAutoScalingGroupProps {
    * Whether instances in the Auto Scaling Group should have public
    * IP addresses associated with them.
    *
-   * @default Use subnet setting
+   * @default - Use subnet setting.
    */
   readonly associatePublicIpAddress?: boolean;
 }
diff --git a/packages/@aws-cdk/aws-autoscaling/lib/lifecycle-hook.ts b/packages/@aws-cdk/aws-autoscaling/lib/lifecycle-hook.ts
index aa94479d00314..2a2a4936afdcf 100644
--- a/packages/@aws-cdk/aws-autoscaling/lib/lifecycle-hook.ts
+++ b/packages/@aws-cdk/aws-autoscaling/lib/lifecycle-hook.ts
@@ -11,7 +11,7 @@ export interface BasicLifecycleHookProps {
   /**
    * Name of the lifecycle hook
    *
-   * @default Automatically generated name
+   * @default - Automatically generated name.
    */
   readonly lifecycleHookName?: string;
 
@@ -26,6 +26,8 @@ export interface BasicLifecycleHookProps {
    * Maximum time between calls to RecordLifecycleActionHeartbeat for the hook
    *
    * If the lifecycle hook times out, perform the action in DefaultResult.
+   *
+   * @default - No heartbeat timeout.
    */
   readonly heartbeatTimeoutSec?: number;
 
@@ -37,7 +39,7 @@ export interface BasicLifecycleHookProps {
   /**
    * Additional data to pass to the lifecycle hook target
    *
-   * @default No metadata
+   * @default - No metadata.
    */
   readonly notificationMetadata?: string;
 
@@ -49,7 +51,7 @@ export interface BasicLifecycleHookProps {
   /**
    * The role that allows publishing to the notification target
    *
-   * @default A role is automatically created
+   * @default - A role is automatically created.
    */
   readonly role?: iam.IRole;
 }
diff --git a/packages/@aws-cdk/aws-autoscaling/lib/scheduled-action.ts b/packages/@aws-cdk/aws-autoscaling/lib/scheduled-action.ts
index ba11d59519abe..a447fa61ebbc0 100644
--- a/packages/@aws-cdk/aws-autoscaling/lib/scheduled-action.ts
+++ b/packages/@aws-cdk/aws-autoscaling/lib/scheduled-action.ts
@@ -20,14 +20,14 @@ export interface BasicScheduledActionProps {
   /**
    * When this scheduled action becomes active.
    *
-   * @default The rule is activate immediately
+   * @default - The rule is activate immediately.
    */
   readonly startTime?: Date
 
   /**
    * When this scheduled action expires.
    *
-   * @default The rule never expires.
+   * @default - The rule never expires.
    */
   readonly endTime?: Date;
 
@@ -38,7 +38,7 @@ export interface BasicScheduledActionProps {
    *
    * At least one of maxCapacity, minCapacity, or desiredCapacity must be supplied.
    *
-   * @default No new minimum capacity
+   * @default - No new minimum capacity.
    */
   readonly minCapacity?: number;
 
@@ -49,7 +49,7 @@ export interface BasicScheduledActionProps {
    *
    * At least one of maxCapacity, minCapacity, or desiredCapacity must be supplied.
    *
-   * @default No new maximum capacity
+   * @default - No new maximum capacity.
    */
   readonly maxCapacity?: number;
 
@@ -59,6 +59,8 @@ export interface BasicScheduledActionProps {
    * At the scheduled time, set the desired capacity to the given capacity.
    *
    * At least one of maxCapacity, minCapacity, or desiredCapacity must be supplied.
+   *
+   * @default - No new desired capacity.
    */
   readonly desiredCapacity?: number;
 }
diff --git a/packages/@aws-cdk/aws-autoscaling/lib/target-tracking-scaling-policy.ts b/packages/@aws-cdk/aws-autoscaling/lib/target-tracking-scaling-policy.ts
index 6e8b54a9b059d..7074f87d12882 100644
--- a/packages/@aws-cdk/aws-autoscaling/lib/target-tracking-scaling-policy.ts
+++ b/packages/@aws-cdk/aws-autoscaling/lib/target-tracking-scaling-policy.ts
@@ -27,14 +27,14 @@ export interface BaseTargetTrackingProps {
   /**
    * Period after a scaling completes before another scaling activity can start.
    *
-   * @default The default cooldown configured on the AutoScalingGroup
+   * @default - The default cooldown configured on the AutoScalingGroup.
    */
   readonly cooldownSeconds?: number;
 
   /**
    * Estimated time until a newly launched instance can send metrics to CloudWatch.
    *
-   * @default Same as the cooldown
+   * @default - Same as the cooldown.
    */
   readonly estimatedInstanceWarmupSeconds?: number;
 }
@@ -55,6 +55,8 @@ export interface BasicTargetTrackingScalingPolicyProps extends BaseTargetTrackin
    * the target value, scaling in will happen in the metric is lower than the target value.
    *
    * Exactly one of customMetric or predefinedMetric must be specified.
+   *
+   * @default - No predefined metric.
    */
   readonly predefinedMetric?: PredefinedMetric;
 
@@ -65,6 +67,8 @@ export interface BasicTargetTrackingScalingPolicyProps extends BaseTargetTrackin
    * the target value, scaling in will happen in the metric is lower than the target value.
    *
    * Exactly one of customMetric or predefinedMetric must be specified.
+   *
+   * @default - No custom metric.
    */
   readonly customMetric?: cloudwatch.Metric;
 
@@ -76,7 +80,7 @@ export interface BasicTargetTrackingScalingPolicyProps extends BaseTargetTrackin
    *
    * app/<load-balancer-name>/<load-balancer-id>/targetgroup/<target-group-name>/<target-group-id>
    *
-   * @default No resource label
+   * @default - No resource label.
    */
   readonly resourceLabel?: string;
 }
diff --git a/packages/@aws-cdk/aws-certificatemanager/lib/certificate.ts b/packages/@aws-cdk/aws-certificatemanager/lib/certificate.ts
index b96de44a7474e..4f2f05c215798 100644
--- a/packages/@aws-cdk/aws-certificatemanager/lib/certificate.ts
+++ b/packages/@aws-cdk/aws-certificatemanager/lib/certificate.ts
@@ -26,6 +26,8 @@ export interface CertificateProps {
    * Alternative domain names on your certificate.
    *
    * Use this to register alternative domain names that represent the same site.
+   *
+   * @default - No additional FQDNs will be included as alternative domain names.
    */
   readonly subjectAlternativeNames?: string[];
 
@@ -34,7 +36,7 @@ export interface CertificateProps {
    *
    * Has to be a superdomain of the requested domain.
    *
-   * @default Apex domain is used for every domain that's not overridden.
+   * @default - Apex domain is used for every domain that's not overridden.
    */
   readonly validationDomains?: {[domainName: string]: string};
 }
diff --git a/packages/@aws-cdk/aws-cloudformation/lib/custom-resource.ts b/packages/@aws-cdk/aws-cloudformation/lib/custom-resource.ts
index c4cd4d10cecfe..29746da866f9c 100644
--- a/packages/@aws-cdk/aws-cloudformation/lib/custom-resource.ts
+++ b/packages/@aws-cdk/aws-cloudformation/lib/custom-resource.ts
@@ -40,6 +40,8 @@ export interface CustomResourceProps {
 
   /**
    * Properties to pass to the Lambda
+   *
+   * @default - No properties.
    */
   readonly properties?: Properties;
 
@@ -61,6 +63,8 @@ export interface CustomResourceProps {
    *
    * @see
    * https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cfn-customresource.html#aws-cfn-resource-type-name
+   *
+   * @default - AWS::CloudFormation::CustomResource
    */
   readonly resourceType?: string;
 }
diff --git a/packages/@aws-cdk/aws-cloudfront/lib/web_distribution.ts b/packages/@aws-cdk/aws-cloudfront/lib/web_distribution.ts
index ee59dd2f44c40..8356043ca04e0 100644
--- a/packages/@aws-cdk/aws-cloudfront/lib/web_distribution.ts
+++ b/packages/@aws-cdk/aws-cloudfront/lib/web_distribution.ts
@@ -52,7 +52,7 @@ export interface AliasConfiguration {
    *
    * See the notes on SSLMethod if you wish to use other SSL termination types.
    *
-   * @default SNI
+   * @default SSLMethod.SNI
    * @see https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ViewerCertificate.html
    */
   readonly sslMethod?: SSLMethod;
@@ -63,7 +63,7 @@ export interface AliasConfiguration {
    * CloudFront serves your objects only to browsers or devices that support at
    * least the SSL version that you specify.
    *
-   * @default securityPolicy: SSLv3 if sslMethod VIP, TLSv1 if sslMethod SNI
+   * @default - SSLv3 if sslMethod VIP, TLSv1 if sslMethod SNI
    */
   readonly securityPolicy?: SecurityPolicyProtocol;
 }
@@ -108,7 +108,7 @@ export interface LoggingConfiguration {
   /**
    * Bucket to log requests to
    *
-   * @default A logging bucket is automatically created
+   * @default - A logging bucket is automatically created.
    */
   readonly bucket?: s3.IBucket,
 
@@ -122,7 +122,7 @@ export interface LoggingConfiguration {
   /**
    * Where in the bucket to store logs
    *
-   * @default No prefix
+   * @default - No prefix.
    */
   readonly prefix?: string
 }
@@ -162,7 +162,7 @@ export interface SourceConfiguration {
   /**
    * Any additional headers to pass to the origin
    *
-   * @default no additional headers are passed
+   * @default - No additional headers are passed.
    */
   readonly originHeaders?: { [key: string]: string };
 }
@@ -193,28 +193,28 @@ export interface CustomOriginConfig {
   /**
    * The keep alive timeout when making calls in seconds.
    *
-   * @default: 5 seconds
+   * @default 5
    */
   readonly originKeepaliveTimeoutSeconds?: number,
 
   /**
    * The protocol (http or https) policy to use when interacting with the origin.
    *
-   * @default: HttpsOnly
+   * @default OriginProtocolPolicy.HttpsOnly
    */
   readonly originProtocolPolicy?: OriginProtocolPolicy,
 
   /**
    * The read timeout when calling the origin in seconds
    *
-   * @default 30 seconds
+   * @default 30
    */
   readonly originReadTimeoutSeconds?: number
 
   /**
    * The SSL versions to use when interacting with the origin.
    *
-   * @default [TLSv1_2]
+   * @default OriginSslPolicy.TLSv1_2
    */
   readonly allowedOriginSSLVersions?: OriginSslPolicy[];
 
@@ -370,19 +370,21 @@ export interface CloudFrontWebDistributionProps {
   /**
    * AliasConfiguration is used to configured CloudFront to respond to requests on custom domain names.
    *
-   * @default none
+   * @default - None.
    */
   readonly aliasConfiguration?: AliasConfiguration;
 
   /**
-   * A comment for this distribution in the cloud front console.
+   * A comment for this distribution in the CloudFront console.
+   *
+   * @default - No comment is added to distribution.
    */
   readonly comment?: string;
 
   /**
    * The default object to serve.
    *
-   * @default "index.html"
+   * @default - "index.html" is served.
    */
   readonly defaultRootObject?: string;
 
@@ -403,7 +405,7 @@ export interface CloudFrontWebDistributionProps {
   /**
    * The price class for the distribution (this impacts how many locations CloudFront uses for your distribution, and billing)
    *
-   * @default PriceClass_100: the cheapest option for CloudFront is picked by default.
+   * @default PriceClass.PriceClass100 the cheapest option for CloudFront is picked by default.
    */
   readonly priceClass?: PriceClass;
 
@@ -424,17 +426,25 @@ export interface CloudFrontWebDistributionProps {
    * You can pass an empty object ({}) to have us auto create a bucket for logging.
    * Omission of this property indicates no logging is to be enabled.
    *
-   * @default: no logging is enabled by default.
+   * @default - no logging is enabled by default.
    */
   readonly loggingConfig?: LoggingConfiguration;
 
   /**
-   * How CloudFront should handle requests that are no successful (eg PageNotFound)
+   * How CloudFront should handle requests that are not successful (eg PageNotFound)
+   *
+   * By default, CloudFront does not replace HTTP status codes in the 4xx and 5xx range
+   * with custom error messages. CloudFront does not cache HTTP status codes.
+   *
+   * @default - No custom error configuration.
    */
   readonly errorConfigurations?: CfnDistribution.CustomErrorResponseProperty[];
 
   /**
-   * Optional AWS WAF WebACL to associate with this CloudFront distribution
+   * Unique identifier that specifies the AWS WAF web ACL to associate with this CloudFront distribution.
+   * @see https://docs.aws.amazon.com/waf/latest/developerguide/what-is-aws-waf.html
+   *
+   * @default - No AWS Web Application Firewall web access control list (web ACL).
    */
   readonly webACLId?: string;
 
diff --git a/packages/@aws-cdk/aws-cloudtrail/lib/index.ts b/packages/@aws-cdk/aws-cloudtrail/lib/index.ts
index 8eee3364e6ebd..da8ce991cfc86 100644
--- a/packages/@aws-cdk/aws-cloudtrail/lib/index.ts
+++ b/packages/@aws-cdk/aws-cloudtrail/lib/index.ts
@@ -14,12 +14,14 @@ export interface TrailProps {
    * For most services, events are recorded in the region where the action occurred.
    * For global services such as AWS Identity and Access Management (IAM), AWS STS, Amazon CloudFront, and Route 53,
    * events are delivered to any trail that includes global services, and are logged as occurring in US East (N. Virginia) Region.
+   *
    * @default true
    */
   readonly includeGlobalServiceEvents?: boolean;
 
   /**
    * Whether or not this trail delivers log files from multiple regions to a single S3 bucket for a single account.
+   *
    * @default true
    */
   readonly isMultiRegionTrail?: boolean;
@@ -35,8 +37,9 @@ export interface TrailProps {
    * Management events can also include non-API events that occur in your account.
    * For example, when a user logs in to your account, CloudTrail logs the ConsoleLogin event.
    *
-   * If managementEvents is undefined, we'll not log management events by default.
    * @param managementEvents the management configuration type to log
+   *
+   * @default - Management events will not be logged.
    */
   readonly managementEvents?: ReadWriteType;
 
@@ -46,6 +49,7 @@ export interface TrailProps {
    * This feature is built using industry standard algorithms: SHA-256 for hashing and SHA-256 with RSA for digital signing.
    * This makes it computationally infeasible to modify, delete or forge CloudTrail log files without detection.
    * You can use the AWS CLI to validate the files in the location where CloudTrail delivered them.
+   *
    * @default true
    */
   readonly enableFileValidation?: boolean;
@@ -53,34 +57,40 @@ export interface TrailProps {
   /**
    * If CloudTrail pushes logs to CloudWatch Logs in addition to S3.
    * Disabled for cost out of the box.
+   *
    * @default false
    */
   readonly sendToCloudWatchLogs?: boolean;
 
   /**
    * How long to retain logs in CloudWatchLogs. Ignored if sendToCloudWatchLogs is false
+   *
    *  @default logs.RetentionDays.OneYear
    */
   readonly cloudWatchLogsRetentionTimeDays?: logs.RetentionDays;
 
   /** The AWS Key Management Service (AWS KMS) key ID that you want to use to encrypt CloudTrail logs.
-   * @default none
+   *
+   * @default - No encryption.
    */
   readonly kmsKey?: kms.IKey;
 
   /** The name of an Amazon SNS topic that is notified when new log files are published.
-   * @default none
+   *
+   * @default - No notifications.
    */
   readonly snsTopic?: string; // TODO: fix to use L2 SNS
 
   /**
    * The name of the trail. We recoomend customers do not set an explicit name.
-   * @default the CloudFormation generated neme
+   *
+   * @default - AWS CloudFormation generated name.
    */
   readonly trailName?: string;
 
   /** An Amazon S3 object key prefix that precedes the name of all log files.
-   * @default none
+   *
+   * @default - No prefix.
    */
   readonly s3KeyPrefix?: string;
 }
diff --git a/packages/@aws-cdk/aws-cloudwatch/lib/metric.ts b/packages/@aws-cdk/aws-cloudwatch/lib/metric.ts
index c88e299580188..da81e2022beda 100644
--- a/packages/@aws-cdk/aws-cloudwatch/lib/metric.ts
+++ b/packages/@aws-cdk/aws-cloudwatch/lib/metric.ts
@@ -12,7 +12,7 @@ export interface MetricProps {
   /**
    * Dimensions of the metric
    *
-   * @default No dimensions
+   * @default - No dimensions.
    */
   readonly dimensions?: DimensionHash;
 
@@ -248,7 +248,7 @@ export interface MetricOptions {
   /**
    * Dimensions of the metric
    *
-   * @default No dimensions
+   * @default - No dimensions.
    */
   readonly dimensions?: DimensionHash;
 
@@ -357,6 +357,8 @@ export interface MetricAlarmProps {
    * Specifies whether to evaluate the data and potentially change the alarm state if there are too few data points to be statistically significant.
    *
    * Used only for alarms that are based on percentiles.
+   *
+   * @default - Not configured.
    */
   readonly evaluateLowSampleCountPercentile?: string;
 
diff --git a/packages/@aws-cdk/aws-codebuild/lib/project.ts b/packages/@aws-cdk/aws-codebuild/lib/project.ts
index 47f2b451b97f0..faebadbb2de75 100644
--- a/packages/@aws-cdk/aws-codebuild/lib/project.ts
+++ b/packages/@aws-cdk/aws-codebuild/lib/project.ts
@@ -350,12 +350,16 @@ export interface CommonProjectProps {
   /**
    * A description of the project. Use the description to identify the purpose
    * of the project.
+   *
+   * @default - No description.
    */
   readonly description?: string;
 
   /**
    * Filename or contents of buildspec in JSON format.
    * @see https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec-ref-example
+   *
+   * @default - Empty buildspec.
    */
   readonly buildSpec?: any;
 
@@ -368,7 +372,7 @@ export interface CommonProjectProps {
    * This feature can also be used without a source, to simply run an
    * arbitrary script in a serverless way.
    *
-   * @default No asset build script
+   * @default - No asset build script.
    */
   readonly buildScriptAsset?: assets.Asset;
 
@@ -381,24 +385,29 @@ export interface CommonProjectProps {
 
   /**
    * Service Role to assume while running the build.
-   * If not specified, a role will be created.
+   *
+   * @default - A role will be created.
    */
   readonly role?: iam.IRole;
 
   /**
    * Encryption key to use to read and write artifacts.
-   * If not specified, a role will be created.
+   *
+   * @default - The AWS-managed CMK for Amazon Simple Storage Service (Amazon S3) is used.
    */
   readonly encryptionKey?: kms.IKey;
 
   /**
    * Caching strategy to use.
+   *
    * @default Cache.none
    */
   readonly cache?: Cache;
 
   /**
    * Build environment to use for the build.
+   *
+   * @default BuildEnvironment.LinuxBuildImage.STANDARD_1_0
    */
   readonly environment?: BuildEnvironment;
 
@@ -406,6 +415,8 @@ export interface CommonProjectProps {
    * Indicates whether AWS CodeBuild generates a publicly accessible URL for
    * your project's build badge. For more information, see Build Badges Sample
    * in the AWS CodeBuild User Guide.
+   *
+   * @default false
    */
   readonly badge?: boolean;
 
@@ -413,16 +424,22 @@ export interface CommonProjectProps {
    * The number of minutes after which AWS CodeBuild stops the build if it's
    * not complete. For valid values, see the timeoutInMinutes field in the AWS
    * CodeBuild User Guide.
+   *
+   * @default 60
    */
   readonly timeout?: number;
 
   /**
    * Additional environment variables to add to the build environment.
+   *
+   * @default - No additional environment variables are specified.
    */
   readonly environmentVariables?: { [name: string]: BuildEnvironmentVariable };
 
   /**
    * The physical, human-readable name of the CodeBuild Project.
+   *
+   * @default - Name is automatically generated.
    */
   readonly projectName?: string;
 
@@ -430,6 +447,8 @@ export interface CommonProjectProps {
    * VPC network to place codebuild network interfaces
    *
    * Specify this if the codebuild project needs to access resources in a VPC.
+   *
+   * @default - No VPC is specified.
    */
   readonly vpc?: ec2.IVpc;
 
@@ -438,7 +457,7 @@ export interface CommonProjectProps {
    *
    * Only used if 'vpc' is supplied.
    *
-   * @default All private subnets
+   * @default - All private subnets.
    */
   readonly subnetSelection?: ec2.SubnetSelection;
 
@@ -448,6 +467,8 @@ export interface CommonProjectProps {
    *
    * Only used if 'vpc' is supplied.
    *
+   * @default - Security group will be automatically created.
+   *
    */
   readonly securityGroups?: ec2.ISecurityGroup[];
 
@@ -469,7 +490,7 @@ export interface ProjectProps extends CommonProjectProps {
    * *Note*: if {@link NoSource} is given as the source,
    * then you need to provide an explicit `buildSpec`.
    *
-   * @default NoSource
+   * @default - NoSource
    */
   readonly source?: BuildSource;
 
@@ -485,7 +506,7 @@ export interface ProjectProps extends CommonProjectProps {
    * The secondary sources for the Project.
    * Can be also added after the Project has been created by using the {@link Project#addSecondarySource} method.
    *
-   * @default []
+   * @default - No secondary sources.
    * @see https://docs.aws.amazon.com/codebuild/latest/userguide/sample-multi-in-out.html
    */
   readonly secondarySources?: BuildSource[];
@@ -494,7 +515,7 @@ export interface ProjectProps extends CommonProjectProps {
    * The secondary artifacts for the Project.
    * Can also be added after the Project has been created by using the {@link Project#addSecondaryArtifact} method.
    *
-   * @default []
+   * @default - No secondary artifacts.
    * @see https://docs.aws.amazon.com/codebuild/latest/userguide/sample-multi-in-out.html
    */
   readonly secondaryArtifacts?: BuildArtifacts[];
diff --git a/packages/@aws-cdk/aws-codecommit/lib/repository.ts b/packages/@aws-cdk/aws-codecommit/lib/repository.ts
index efa5a0afc3910..518f6ffb0a8a6 100644
--- a/packages/@aws-cdk/aws-codecommit/lib/repository.ts
+++ b/packages/@aws-cdk/aws-codecommit/lib/repository.ts
@@ -208,6 +208,8 @@ export interface RepositoryProps {
   /**
    * A description of the repository. Use the description to identify the
    * purpose of the repository.
+   *
+   * @default - No description.
    */
   readonly description?: string;
 }
diff --git a/packages/@aws-cdk/aws-codedeploy/lib/lambda/deployment-group.ts b/packages/@aws-cdk/aws-codedeploy/lib/lambda/deployment-group.ts
index 7deae49743923..379fcfa2b57cf 100644
--- a/packages/@aws-cdk/aws-codedeploy/lib/lambda/deployment-group.ts
+++ b/packages/@aws-cdk/aws-codedeploy/lib/lambda/deployment-group.ts
@@ -38,14 +38,14 @@ export interface LambdaDeploymentGroupProps {
   /**
    * The reference to the CodeDeploy Lambda Application that this Deployment Group belongs to.
    *
-   * @default one will be created for you
+   * @default - One will be created for you.
    */
   readonly application?: ILambdaApplication;
 
   /**
    * The physical, human-readable name of the CodeDeploy Deployment Group.
    *
-   * @default an auto-generated name will be used
+   * @default - An auto-generated name will be used.
    */
   readonly deploymentGroupName?: string;
 
@@ -71,7 +71,7 @@ export interface LambdaDeploymentGroupProps {
   /**
    * The service Role of this Deployment Group.
    *
-   * @default a new Role will be created.
+   * @default - A new Role will be created.
    */
   readonly role?: iam.IRole;
 
@@ -85,11 +85,15 @@ export interface LambdaDeploymentGroupProps {
 
   /**
    * The Lambda function to run before traffic routing starts.
+   *
+   * @default - None.
    */
   readonly preHook?: lambda.IFunction;
 
   /**
    * The Lambda function to run after traffic routing starts.
+   *
+   * @default - None.
    */
   readonly postHook?: lambda.IFunction;
 
@@ -102,6 +106,8 @@ export interface LambdaDeploymentGroupProps {
 
   /**
    * The auto-rollback configuration for this Deployment Group.
+   *
+   * @default - default AutoRollbackConfig.
    */
   readonly autoRollback?: AutoRollbackConfig;
 }
diff --git a/packages/@aws-cdk/aws-codedeploy/lib/server/deployment-group.ts b/packages/@aws-cdk/aws-codedeploy/lib/server/deployment-group.ts
index 2dd9e12c587fd..7d426fa27dbe1 100644
--- a/packages/@aws-cdk/aws-codedeploy/lib/server/deployment-group.ts
+++ b/packages/@aws-cdk/aws-codedeploy/lib/server/deployment-group.ts
@@ -135,20 +135,22 @@ export class InstanceTagSet {
 export interface ServerDeploymentGroupProps {
   /**
    * The CodeDeploy EC2/on-premise Application this Deployment Group belongs to.
-   * If you don't provide one, a new Application will be created.
+   *
+   * @default - A new Application will be created.
    */
   readonly application?: IServerApplication;
 
   /**
    * The service Role of this Deployment Group.
-   * If you don't provide one, a new Role will be created.
+   *
+   * @default - A new Role will be created.
    */
   readonly role?: iam.IRole;
 
   /**
    * The physical, human-readable name of the CodeDeploy Deployment Group.
    *
-   * @default an auto-generated name will be used
+   * @default - An auto-generated name will be used.
    */
   readonly deploymentGroupName?: string;
 
@@ -186,21 +188,21 @@ export interface ServerDeploymentGroupProps {
    * Can be created from either a classic Elastic Load Balancer,
    * or an Application Load Balancer / Network Load Balancer Target Group.
    *
-   * @default the Deployment Group will not have a load balancer defined
+   * @default - Deployment Group will not have a load balancer defined.
    */
   readonly loadBalancer?: LoadBalancer;
 
   /**
    * All EC2 instances matching the given set of tags when a deployment occurs will be added to this Deployment Group.
    *
-   * @default no additional EC2 instances will be added to the Deployment Group
+   * @default - No additional EC2 instances will be added to the Deployment Group.
    */
   readonly ec2InstanceTags?: InstanceTagSet;
 
   /**
    * All on-premise instances matching the given set of tags when a deployment occurs will be added to this Deployment Group.
    *
-   * @default no additional on-premise instances will be added to the Deployment Group
+   * @default - No additional on-premise instances will be added to the Deployment Group.
    */
   readonly onPremiseInstanceTags?: InstanceTagSet;
 
@@ -225,6 +227,8 @@ export interface ServerDeploymentGroupProps {
 
   /**
    * The auto-rollback configuration for this Deployment Group.
+   *
+   * @default - default AutoRollbackConfig.
    */
   readonly autoRollback?: AutoRollbackConfig;
 }
diff --git a/packages/@aws-cdk/aws-codepipeline-actions/lib/jenkins/jenkins-provider.ts b/packages/@aws-cdk/aws-codepipeline-actions/lib/jenkins/jenkins-provider.ts
index 84c868595fb47..322235f37f6ef 100644
--- a/packages/@aws-cdk/aws-codepipeline-actions/lib/jenkins/jenkins-provider.ts
+++ b/packages/@aws-cdk/aws-codepipeline-actions/lib/jenkins/jenkins-provider.ts
@@ -88,12 +88,16 @@ export interface JenkinsProviderProps {
   /**
    * Whether to immediately register a Jenkins Provider for the build category.
    * The Provider will always be registered if you create a {@link JenkinsAction}.
+   *
+   * @default false
    */
   readonly forBuild?: boolean;
 
   /**
    * Whether to immediately register a Jenkins Provider for the test category.
    * The Provider will always be registered if you create a {@link JenkinsTestAction}.
+   *
+   * @default false
    */
   readonly forTest?: boolean;
 }
diff --git a/packages/@aws-cdk/aws-codepipeline/lib/pipeline.ts b/packages/@aws-cdk/aws-codepipeline/lib/pipeline.ts
index 80fc811e7ba20..70e268badb771 100644
--- a/packages/@aws-cdk/aws-codepipeline/lib/pipeline.ts
+++ b/packages/@aws-cdk/aws-codepipeline/lib/pipeline.ts
@@ -64,7 +64,8 @@ export interface StageAddToPipelineProps extends StageProps {
 export interface PipelineProps {
   /**
    * The S3 bucket used by this Pipeline to store artifacts.
-   * If not specified, a new S3 bucket will be created.
+   *
+   * @default - A new S3 bucket will be created.
    */
   readonly artifactBucket?: s3.IBucket;
 
@@ -77,12 +78,15 @@ export interface PipelineProps {
 
   /**
    * Indicates whether to rerun the AWS CodePipeline pipeline after you update it.
+   *
+   * @default false
    */
   readonly restartExecutionOnUpdate?: boolean;
 
   /**
-   * Name of the pipeline. If you don't specify a name,  AWS CloudFormation generates an ID
-   * and uses that for the pipeline name.
+   * Name of the pipeline.
+   *
+   * @default - AWS CloudFormation generates an ID and uses that for the pipeline name.
    */
   readonly pipelineName?: string;
 
@@ -93,6 +97,8 @@ export interface PipelineProps {
    * the construct will automatically create a scaffold Stack containing an S3 Bucket in that region.
    * Note that you will have to `cdk deploy` that Stack before you can deploy your Pipeline-containing Stack.
    * You can query the generated Stacks using the {@link Pipeline#crossRegionScaffoldStacks} property.
+   *
+   * @default - None.
    */
   readonly crossRegionReplicationBuckets?: { [region: string]: string };
 
@@ -100,6 +106,8 @@ export interface PipelineProps {
    * The list of Stages, in order,
    * to create this Pipeline with.
    * You can always add more Stages later by calling {@link Pipeline#addStage}.
+   *
+   * @default - None.
    */
   readonly stages?: StageProps[];
 }
diff --git a/packages/@aws-cdk/aws-cognito/lib/user-pool.ts b/packages/@aws-cdk/aws-cognito/lib/user-pool.ts
index 0256fb2ff6fe6..044bf87ec4693 100644
--- a/packages/@aws-cdk/aws-cognito/lib/user-pool.ts
+++ b/packages/@aws-cdk/aws-cognito/lib/user-pool.ts
@@ -203,33 +203,39 @@ export interface UserPoolTriggers {
 export interface UserPoolProps {
   /**
    * Name of the user pool
-   * @default unique ID
+   *
+   * @default - Unique ID.
    */
   readonly poolName?: string;
 
   /**
    * Method used for user registration & sign in.
    * Allows either username with aliases OR sign in with email, phone, or both.
-   * @default SignInType.USERNAME
+   *
+   * @default SignInType.Username
    */
   readonly signInType?: SignInType;
 
   /**
    * Attributes to allow as username alias.
    * Only valid if signInType is USERNAME
-   * @default no alias
+   *
+   * @default - No alias.
    */
   readonly usernameAliasAttributes?: UserPoolAttribute[];
 
   /**
    * Attributes which Cognito will automatically send a verification message to.
    * Must be either EMAIL, PHONE, or both.
-   * @default no auto verification
+   *
+   * @default - No auto verification.
    */
   readonly autoVerifiedAttributes?: UserPoolAttribute[];
 
   /**
    * Lambda functions to use for supported Cognito triggers.
+   *
+   * @default - No Lambda triggers.
    */
   readonly lambdaTriggers?: UserPoolTriggers;
 }
diff --git a/packages/@aws-cdk/aws-ec2/lib/vpc.ts b/packages/@aws-cdk/aws-ec2/lib/vpc.ts
index 2853c6fa21631..32cabbf516343 100644
--- a/packages/@aws-cdk/aws-ec2/lib/vpc.ts
+++ b/packages/@aws-cdk/aws-ec2/lib/vpc.ts
@@ -420,6 +420,8 @@ export interface VpcProps {
   /**
    * The CIDR range to use for the VPC (e.g. '10.0.0.0/16'). Should be a minimum of /28 and maximum size of /16.
    * The range will be split evenly into two subnets per Availability Zone (one public, one private).
+   *
+   * @default Vpc.DEFAULT_CIDR_RANGE
    */
   readonly cidr?: string;
 
@@ -427,6 +429,8 @@ export interface VpcProps {
    * Indicates whether the instances launched in the VPC get public DNS hostnames.
    * If this attribute is true, instances in the VPC get public DNS hostnames,
    * but only if the enableDnsSupport attribute is also set to true.
+   *
+   * @default true
    */
   readonly enableDnsHostnames?: boolean;
 
@@ -436,15 +440,18 @@ export interface VpcProps {
    * to IP addresses is not enabled. If this attribute is true, queries to the Amazon
    * provided DNS server at the 169.254.169.253 IP address, or the reserved IP address
    * at the base of the VPC IPv4 network range plus two will succeed.
+   *
+   * @default true
    */
   readonly enableDnsSupport?: boolean;
 
   /**
    * The default tenancy of instances launched into the VPC.
-   * By default, instances will be launched with default (shared) tenancy.
    * By setting this to dedicated tenancy, instances will be launched on hardware dedicated
    * to a single AWS customer, unless specifically specified at instance launch time.
    * Please note, not all instance types are usable with Dedicated tenancy.
+   *
+   * @default DefaultInstanceTenancy.Default (shared) tenancy
    */
   readonly defaultInstanceTenancy?: DefaultInstanceTenancy;
 
@@ -467,6 +474,7 @@ export interface VpcProps {
    *
    * For example, if set this to 1 and your subnet configuration is for 3 Public subnets then only
    * one of the Public subnets will have a gateway and all Private subnets will route to this NAT Gateway.
+   *
    * @default maxAZs
    */
   readonly natGateways?: number;
@@ -477,7 +485,7 @@ export interface VpcProps {
    * You can pick a specific group of subnets by specifying the group name;
    * the picked subnets must be public subnets.
    *
-   * @default All public subnets
+   * @default - All public subnets.
    */
   readonly natGatewaySubnets?: SubnetSelection;
 
@@ -511,41 +519,43 @@ export interface VpcProps {
    * `cidrMask` is optional and if not provided the IP space in the VPC will be
    * evenly divided between the requested subnets.
    *
-   * @default the VPC CIDR will be evenly divided between 1 public and 1
-   * private subnet per AZ
+   * @default - The VPC CIDR will be evenly divided between 1 public and 1
+   * private subnet per AZ.
    */
   readonly subnetConfiguration?: SubnetConfiguration[];
 
   /**
    * Indicates whether a VPN gateway should be created and attached to this VPC.
    *
-   * @default true when vpnGatewayAsn or vpnConnections is specified.
+   * @default - true when vpnGatewayAsn or vpnConnections is specified.
    */
   readonly vpnGateway?: boolean;
 
   /**
    * The private Autonomous System Number (ASN) for the VPN gateway.
    *
-   * @default Amazon default ASN
+   * @default - Amazon default ASN.
    */
   readonly vpnGatewayAsn?: number;
 
   /**
    * VPN connections to this VPC.
    *
-   * @default no connections
+   * @default - No connections.
    */
   readonly vpnConnections?: { [id: string]: VpnConnectionOptions }
 
   /**
    * Where to propagate VPN routes.
    *
-   * @default on the route tables associated with private subnets
+   * @default - On the route tables associated with private subnets.
    */
   readonly vpnRoutePropagation?: SubnetSelection[]
 
   /**
    * Gateway endpoints to add to this VPC.
+   *
+   * @default - None.
    */
   readonly gatewayEndpoints?: { [id: string]: GatewayVpcEndpointOptions }
 }
@@ -1032,7 +1042,7 @@ export interface SubnetProps {
   /**
    * Controls if a public IP is associated to an instance at launch
    *
-   * Defaults to true in Subnet.Public, false in Subnet.Private or Subnet.Isolated.
+   * @default true in Subnet.Public, false in Subnet.Private or Subnet.Isolated.
    */
   readonly mapPublicIpOnLaunch?: boolean;
 }
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 6b80ba9625dd0..892d9e6913e09 100644
--- a/packages/@aws-cdk/aws-ecs/lib/base/base-service.ts
+++ b/packages/@aws-cdk/aws-ecs/lib/base/base-service.ts
@@ -39,7 +39,7 @@ export interface BaseServiceProps {
   /**
    * A name for the service.
    *
-   * @default CloudFormation-generated name
+   * @default - CloudFormation-generated name.
    */
   readonly serviceName?: string;
 
@@ -48,7 +48,7 @@ export interface BaseServiceProps {
    * service's DesiredCount value, that can run in a service during a
    * deployment.
    *
-   * @default 100 if daemon, otherwise 200
+   * @default - 100 if daemon, otherwise 200
    */
   readonly maximumPercent?: number;
 
@@ -57,7 +57,7 @@ export interface BaseServiceProps {
    * the Amazon ECS service's DesiredCount value, that must
    * continue to run and remain healthy during a deployment.
    *
-   * @default 0 if daemon, otherwise 50
+   * @default - 0 if daemon, otherwise 50
    */
   readonly minimumHealthyPercent?: number;
 
@@ -70,6 +70,8 @@ export interface BaseServiceProps {
 
   /**
    * Options for enabling AWS Cloud Map service discovery for the service
+   *
+   * @default - AWS Cloud Map service discovery is not enabled.
    */
   readonly serviceDiscoveryOptions?: ServiceDiscoveryOptions;
 
diff --git a/packages/@aws-cdk/aws-ecs/lib/base/task-definition.ts b/packages/@aws-cdk/aws-ecs/lib/base/task-definition.ts
index 09fa5d7d28479..bb21d9061abd0 100644
--- a/packages/@aws-cdk/aws-ecs/lib/base/task-definition.ts
+++ b/packages/@aws-cdk/aws-ecs/lib/base/task-definition.ts
@@ -39,7 +39,7 @@ export interface CommonTaskDefinitionProps {
   /**
    * Namespace for task definition versions
    *
-   * @default Automatically generated name
+   * @default - Automatically generated name.
    */
   readonly family?: string;
 
@@ -49,19 +49,21 @@ export interface CommonTaskDefinitionProps {
    * The role will be used to retrieve container images from ECR and
    * create CloudWatch log groups.
    *
-   * @default An execution role will be automatically created if you use ECR images in your task definition
+   * @default - An execution role will be automatically created if you use ECR images in your task definition.
    */
   readonly executionRole?: iam.IRole;
 
   /**
    * The IAM role assumable by your application code running inside the container
    *
-   * @default A task role is automatically created for you
+   * @default - A task role is automatically created for you.
    */
   readonly taskRole?: iam.IRole;
 
   /**
    * See: https://docs.aws.amazon.com/AmazonECS/latest/developerguide//task_definition_parameters.html#volumes
+   *
+   * @default - No volumes are passed to the Docker daemon on a container instance.
    */
   readonly volumes?: Volume[];
 }
@@ -75,7 +77,7 @@ export interface TaskDefinitionProps extends CommonTaskDefinitionProps {
    *
    * On Fargate, the only supported networking mode is AwsVpc.
    *
-   * @default NetworkMode.Bridge for EC2 tasks, AwsVpc for Fargate tasks.
+   * @default - NetworkMode.Bridge for EC2 tasks, AwsVpc for Fargate tasks.
    */
   readonly networkMode?: NetworkMode;
 
@@ -85,6 +87,8 @@ export interface TaskDefinitionProps extends CommonTaskDefinitionProps {
    * constraints in the task definition and those specified at run time).
    *
    * Not supported in Fargate.
+   *
+   * @default - No placement constraints.
    */
   readonly placementConstraints?: PlacementConstraint[];
 
@@ -95,18 +99,27 @@ export interface TaskDefinitionProps extends CommonTaskDefinitionProps {
 
   /**
    * The number of cpu units used by the task.
+   *
+   * Optional for EC2 tasks and any value can be used.
+   *
+   * Required for Fargate tasks
    * Valid values, which determines your range of valid values for the memory parameter:
    * 256 (.25 vCPU) - Available memory values: 0.5GB, 1GB, 2GB
    * 512 (.5 vCPU) - Available memory values: 1GB, 2GB, 3GB, 4GB
    * 1024 (1 vCPU) - Available memory values: 2GB, 3GB, 4GB, 5GB, 6GB, 7GB, 8GB
    * 2048 (2 vCPU) - Available memory values: Between 4GB and 16GB in 1GB increments
    * 4096 (4 vCPU) - Available memory values: Between 8GB and 30GB in 1GB increments
+   *
+   * @default - CPU units are not specified.
    */
   readonly cpu?: string;
 
   /**
    * The amount (in MiB) of memory used by the task.
    *
+   * Optional for EC2 tasks and any value can be used.
+   *
+   * Required for Fargate tasks
    * This field is required and you must use one of the following values, which determines your range of valid values
    * for the cpu parameter:
    *
@@ -119,6 +132,8 @@ export interface TaskDefinitionProps extends CommonTaskDefinitionProps {
    * Between 4GB and 16GB in 1GB increments - Available cpu values: 2048 (2 vCPU)
    *
    * Between 8GB and 30GB in 1GB increments - Available cpu values: 4096 (4 vCPU)
+   *
+   * @default - Memory used by task is not specified.
    */
   readonly memoryMiB?: string;
 }
diff --git a/packages/@aws-cdk/aws-ecs/lib/container-definition.ts b/packages/@aws-cdk/aws-ecs/lib/container-definition.ts
index 1f0f4a98f4894..d05de2d082f62 100644
--- a/packages/@aws-cdk/aws-ecs/lib/container-definition.ts
+++ b/packages/@aws-cdk/aws-ecs/lib/container-definition.ts
@@ -21,12 +21,14 @@ export interface ContainerDefinitionOptions {
    *
    * If you provide a shell command as a single string, you have to quote command-line arguments.
    *
-   * @default CMD value built into container image
+   * @default - CMD value built into container image.
    */
   readonly command?: string[];
 
   /**
    * The minimum number of CPU units to reserve for the container.
+   *
+   * @default - No minimum CPU units reserved.
    */
   readonly cpu?: number;
 
@@ -40,28 +42,28 @@ export interface ContainerDefinitionOptions {
   /**
    * A list of DNS search domains that are provided to the container.
    *
-   * @default No search domains
+   * @default - No search domains.
    */
   readonly dnsSearchDomains?: string[];
 
   /**
    * A list of DNS servers that Amazon ECS provides to the container.
    *
-   * @default Default DNS servers
+   * @default - Default DNS servers.
    */
   readonly dnsServers?: string[];
 
   /**
    * A key-value map of labels for the container.
    *
-   * @default No labels
+   * @default - No labels.
    */
   readonly dockerLabels?: { [key: string]: string };
 
   /**
    * A list of custom labels for SELinux and AppArmor multi-level security systems.
    *
-   * @default No security labels
+   * @default - No security labels.
    */
   readonly dockerSecurityOptions?: string[];
 
@@ -69,14 +71,15 @@ export interface ContainerDefinitionOptions {
    * The ENTRYPOINT value to pass to the container.
    *
    * @see https://docs.docker.com/engine/reference/builder/#entrypoint
-   * @default Entry point configured in container
+   *
+   * @default - Entry point configured in container.
    */
   readonly entryPoint?: string[];
 
   /**
    * The environment variables to pass to the container.
    *
-   * @default No environment variables
+   * @default - No environment variables.
    */
   readonly environment?: { [key: string]: string };
 
@@ -96,21 +99,21 @@ export interface ContainerDefinitionOptions {
   /**
    * A list of hostnames and IP address mappings to append to the /etc/hosts file on the container.
    *
-   * @default No extra hosts
+   * @default - No extra hosts.
    */
   readonly extraHosts?: { [name: string]: string };
 
   /**
    * Container health check.
    *
-   * @default Health check configuration from container
+   * @default - Health check configuration from container.
    */
   readonly healthCheck?: HealthCheck;
 
   /**
    * The name that Docker uses for the container hostname.
    *
-   * @default Automatic hostname
+   * @default - Automatic hostname.
    */
   readonly hostname?: string;
 
@@ -121,6 +124,8 @@ export interface ContainerDefinitionOptions {
    * is terminated.
    *
    * At least one of memoryLimitMiB and memoryReservationMiB is required for non-Fargate services.
+   *
+   * @default - No memory limit.
    */
   readonly memoryLimitMiB?: number;
 
@@ -133,6 +138,8 @@ export interface ContainerDefinitionOptions {
    * the available memory on the container instance—whichever comes first.
    *
    * At least one of memoryLimitMiB and memoryReservationMiB is required for non-Fargate services.
+   *
+   * @default - No memory reserved.
    */
   readonly memoryReservationMiB?: number;
 
@@ -166,11 +173,15 @@ export interface ContainerDefinitionOptions {
 
   /**
    * Configures a custom log driver for the container.
+   *
+   * @default - Containers use the same logging driver that the Docker daemon uses.
    */
   readonly logging?: LogDriver;
 
   /**
    * Configures Linux Parameters
+   *
+   * @default - No Linux paramters.
    */
   readonly linuxParameters?: LinuxParameters;
 }
diff --git a/packages/@aws-cdk/aws-ecs/lib/ec2/ec2-service.ts b/packages/@aws-cdk/aws-ecs/lib/ec2/ec2-service.ts
index 43337f9215256..207a1fc9baa91 100644
--- a/packages/@aws-cdk/aws-ecs/lib/ec2/ec2-service.ts
+++ b/packages/@aws-cdk/aws-ecs/lib/ec2/ec2-service.ts
@@ -23,7 +23,7 @@ export interface Ec2ServiceProps extends BaseServiceProps {
    *
    * (Only applicable in case the TaskDefinition is configured for AwsVpc networking)
    *
-   * @default Private subnets
+   * @default - Private subnets.
    */
   readonly vpcSubnets?: ec2.SubnetSelection;
 
@@ -32,21 +32,21 @@ export interface Ec2ServiceProps extends BaseServiceProps {
    *
    * (Only applicable in case the TaskDefinition is configured for AwsVpc networking)
    *
-   * @default A new security group is created
+   * @default - A new security group is created.
    */
   readonly securityGroup?: ec2.ISecurityGroup;
 
   /**
    * Placement constraints
    *
-   * @default No constraints
+   * @default - No constraints.
    */
   readonly placementConstraints?: PlacementConstraint[];
 
   /**
    * Placement strategies
    *
-   * @default No strategies
+   * @default - No strategies.
    */
   readonly placementStrategies?: PlacementStrategy[];
 
diff --git a/packages/@aws-cdk/aws-ecs/lib/ec2/ec2-task-definition.ts b/packages/@aws-cdk/aws-ecs/lib/ec2/ec2-task-definition.ts
index 5c773a0cba82e..7d2c572155e9a 100644
--- a/packages/@aws-cdk/aws-ecs/lib/ec2/ec2-task-definition.ts
+++ b/packages/@aws-cdk/aws-ecs/lib/ec2/ec2-task-definition.ts
@@ -11,7 +11,7 @@ export interface Ec2TaskDefinitionProps extends CommonTaskDefinitionProps {
    *
    * On Fargate, the only supported networking mode is AwsVpc.
    *
-   * @default NetworkMode.Bridge for EC2 tasks, AwsVpc for Fargate tasks.
+   * @default - NetworkMode.Bridge for EC2 tasks, AwsVpc for Fargate tasks.
    */
   readonly networkMode?: NetworkMode;
 
@@ -21,6 +21,8 @@ export interface Ec2TaskDefinitionProps extends CommonTaskDefinitionProps {
    * constraints in the task definition and those specified at run time).
    *
    * Not supported in Fargate.
+   *
+   * @default - No placement constraints.
    */
   readonly placementConstraints?: PlacementConstraint[];
 }
diff --git a/packages/@aws-cdk/aws-ecs/lib/fargate/fargate-service.ts b/packages/@aws-cdk/aws-ecs/lib/fargate/fargate-service.ts
index 6e49554d39909..8a7c03d0937cf 100644
--- a/packages/@aws-cdk/aws-ecs/lib/fargate/fargate-service.ts
+++ b/packages/@aws-cdk/aws-ecs/lib/fargate/fargate-service.ts
@@ -18,21 +18,21 @@ export interface FargateServiceProps extends BaseServiceProps {
   /**
    * Assign public IP addresses to each task
    *
-   * @default Use subnet default
+   * @default - Use subnet default.
    */
   readonly assignPublicIp?: boolean;
 
   /**
    * In what subnets to place the task's ENIs
    *
-   * @default Private subnets
+   * @default - Private subnets.
    */
   readonly vpcSubnets?: ec2.SubnetSelection;
 
   /**
    * Existing security group to use for the tasks
    *
-   * @default A new security group is created
+   * @default - A new security group is created.
    */
   readonly securityGroup?: ec2.ISecurityGroup;
 
diff --git a/packages/@aws-cdk/aws-ecs/lib/linux-parameters.ts b/packages/@aws-cdk/aws-ecs/lib/linux-parameters.ts
index 154d7bea07811..4630cf7a18420 100644
--- a/packages/@aws-cdk/aws-ecs/lib/linux-parameters.ts
+++ b/packages/@aws-cdk/aws-ecs/lib/linux-parameters.ts
@@ -7,11 +7,15 @@ import { CfnTaskDefinition } from './ecs.generated';
 export interface LinuxParametersProps {
   /**
    * Whether the init process is enabled
+   *
+   * @default false
    */
   readonly initProcessEnabled?: boolean;
 
   /**
    * The shared memory size
+   *
+   * @default No shared memory.
    */
   readonly sharedMemorySize?: number;
 }
diff --git a/packages/@aws-cdk/aws-ecs/lib/load-balanced-ecs-service.ts b/packages/@aws-cdk/aws-ecs/lib/load-balanced-ecs-service.ts
index 3bcf1f7ae890c..9dcf49af944bd 100644
--- a/packages/@aws-cdk/aws-ecs/lib/load-balanced-ecs-service.ts
+++ b/packages/@aws-cdk/aws-ecs/lib/load-balanced-ecs-service.ts
@@ -14,6 +14,8 @@ export interface LoadBalancedEc2ServiceProps extends LoadBalancedServiceBaseProp
    * is terminated.
    *
    * At least one of memoryLimitMiB and memoryReservationMiB is required.
+   *
+   * @default - No memory limit.
    */
   readonly memoryLimitMiB?: number;
 
@@ -26,6 +28,8 @@ export interface LoadBalancedEc2ServiceProps extends LoadBalancedServiceBaseProp
    * the available memory on the container instance—whichever comes first.
    *
    * At least one of memoryLimitMiB and memoryReservationMiB is required.
+   *
+   * @default - No memory reserved.
    */
   readonly memoryReservationMiB?: number;
 }
diff --git a/packages/@aws-cdk/aws-ecs/lib/load-balanced-fargate-service-applet.ts b/packages/@aws-cdk/aws-ecs/lib/load-balanced-fargate-service-applet.ts
index 4225dc27daa2c..0793390f85e9e 100644
--- a/packages/@aws-cdk/aws-ecs/lib/load-balanced-fargate-service-applet.ts
+++ b/packages/@aws-cdk/aws-ecs/lib/load-balanced-fargate-service-applet.ts
@@ -80,26 +80,32 @@ export interface LoadBalancedFargateServiceAppletProps extends cdk.StackProps {
    */
   readonly desiredCount?: number;
 
-  /*
+  /**
    * Domain name for the service, e.g. api.example.com
+   *
+   * @default - No domain name.
    */
   readonly domainName?: string;
 
   /**
    * Route53 hosted zone for the domain, e.g. "example.com."
+   *
+   * @default - No Route53 hosted domain zone.
    */
   readonly domainZone?: string;
 
   /**
    * Certificate Manager certificate to associate with the load balancer.
    * Setting this option will set the load balancer port to 443.
+   *
+   * @default - No certificate associated with the load balancer.
    */
   readonly certificate?: string;
 
   /**
    * Environment variables to pass to the container
    *
-   * @default No environment variables
+   * @default - No environment variables.
    */
   readonly environment?: { [key: string]: string };
 }
diff --git a/packages/@aws-cdk/aws-ecs/lib/load-balanced-fargate-service.ts b/packages/@aws-cdk/aws-ecs/lib/load-balanced-fargate-service.ts
index 713bd335736b5..700606ceccc31 100644
--- a/packages/@aws-cdk/aws-ecs/lib/load-balanced-fargate-service.ts
+++ b/packages/@aws-cdk/aws-ecs/lib/load-balanced-fargate-service.ts
@@ -53,13 +53,17 @@ export interface LoadBalancedFargateServiceProps extends LoadBalancedServiceBase
    */
   readonly publicTasks?: boolean;
 
-  /*
+  /**
    * Domain name for the service, e.g. api.example.com
+   *
+   * @default - No domain name.
    */
   readonly domainName?: string;
 
   /**
    * Route53 hosted zone for the domain, e.g. "example.com."
+   *
+   * @default - No Route53 hosted domain zone.
    */
   readonly domainZone?: IHostedZone;
 
diff --git a/packages/@aws-cdk/aws-ecs/lib/load-balanced-service-base.ts b/packages/@aws-cdk/aws-ecs/lib/load-balanced-service-base.ts
index 5d6429ad6ee2d..5bf79162891a1 100644
--- a/packages/@aws-cdk/aws-ecs/lib/load-balanced-service-base.ts
+++ b/packages/@aws-cdk/aws-ecs/lib/load-balanced-service-base.ts
@@ -44,6 +44,7 @@ export interface LoadBalancedServiceBaseProps {
 
   /**
    * Whether to create an application load balancer or a network load balancer
+   *
    * @default application
    */
   readonly loadBalancerType?: LoadBalancerType
@@ -51,13 +52,15 @@ export interface LoadBalancedServiceBaseProps {
   /**
    * Certificate Manager certificate to associate with the load balancer.
    * Setting this option will set the load balancer port to 443.
+   *
+   * @default - No certificate associated with the load balancer.
    */
   readonly certificate?: ICertificate;
 
   /**
    * Environment variables to pass to the container
    *
-   * @default No environment variables
+   * @default - No environment variables.
    */
   readonly environment?: { [key: string]: string };
 }
diff --git a/packages/@aws-cdk/aws-ecs/lib/log-drivers/aws-log-driver.ts b/packages/@aws-cdk/aws-ecs/lib/log-drivers/aws-log-driver.ts
index ca49f9dd01e27..b5753f2c9183d 100644
--- a/packages/@aws-cdk/aws-ecs/lib/log-drivers/aws-log-driver.ts
+++ b/packages/@aws-cdk/aws-ecs/lib/log-drivers/aws-log-driver.ts
@@ -23,7 +23,7 @@ export interface AwsLogDriverProps {
   /**
    * The log group to log to
    *
-   * @default A log group is automatically created
+   * @default - A log group is automatically created.
    */
   readonly logGroup?: logs.ILogGroup;
 
@@ -31,7 +31,7 @@ export interface AwsLogDriverProps {
    * The number of days log events are kept in CloudWatch Logs when the log
    * group is automatically created by this construct.
    *
-   * @default logs never expire
+   * @default - Logs never expire.
    */
   readonly logRetentionDays?: logs.RetentionDays;
 
@@ -41,6 +41,8 @@ export interface AwsLogDriverProps {
    * A log message consists of a line that matches the pattern and any
    * following lines that don’t match the pattern. Thus the matched line is
    * the delimiter between log messages.
+   *
+   * @default - No multiline matching.
    */
   readonly datetimeFormat?: string;
 
@@ -50,6 +52,10 @@ export interface AwsLogDriverProps {
    * A log message consists of a line that matches the pattern and any
    * following lines that don’t match the pattern. Thus the matched line is
    * the delimiter between log messages.
+   *
+   * This option is ignored if datetimeFormat is also configured.
+   *
+   * @default - No multiline matching.
    */
   readonly multilinePattern?: string;
 }
diff --git a/packages/@aws-cdk/aws-elasticloadbalancing/lib/load-balancer.ts b/packages/@aws-cdk/aws-elasticloadbalancing/lib/load-balancer.ts
index 47c04e61ed6b9..719d558942405 100644
--- a/packages/@aws-cdk/aws-elasticloadbalancing/lib/load-balancer.ts
+++ b/packages/@aws-cdk/aws-elasticloadbalancing/lib/load-balancer.ts
@@ -27,6 +27,8 @@ export interface LoadBalancerProps {
    * What listeners to set up for the load balancer.
    *
    * Can also be added by .addListener()
+   *
+   * @default -
    */
   readonly listeners?: LoadBalancerListener[];
 
@@ -34,6 +36,8 @@ export interface LoadBalancerProps {
    * What targets to load balance to.
    *
    * Can also be added by .addTarget()
+   *
+   * @default - None.
    */
   readonly targets?: ILoadBalancerTarget[];
 
@@ -41,6 +45,8 @@ export interface LoadBalancerProps {
    * Health check settings for the load balancing targets.
    *
    * Not required but recommended.
+   *
+   * @default - None.
    */
   readonly healthCheck?: HealthCheck;
 }
diff --git a/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/alb/application-listener-rule.ts b/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/alb/application-listener-rule.ts
index 3520f5a0aadc9..d72ebfb356b48 100644
--- a/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/alb/application-listener-rule.ts
+++ b/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/alb/application-listener-rule.ts
@@ -19,12 +19,16 @@ export interface BaseApplicationListenerRuleProps {
   /**
    * Target groups to forward requests to. Only one of `targetGroups` or
    * `fixedResponse` can be specified.
+   *
+   * @default - No target groups.
    */
   readonly targetGroups?: IApplicationTargetGroup[];
 
   /**
    * Fixed response to return. Only one of `fixedResponse` or
    * `targetGroups` can be specified.
+   *
+   * @default - No fixed response.
    */
   readonly fixedResponse?: FixedResponse;
 
@@ -35,7 +39,7 @@ export interface BaseApplicationListenerRuleProps {
    *
    * @see https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-listeners.html#host-conditions
    *
-   * @default No host condition
+   * @default - No host condition.
    */
   readonly hostHeader?: string;
 
@@ -46,7 +50,7 @@ export interface BaseApplicationListenerRuleProps {
    *
    * @see https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-listeners.html#path-conditions
    *
-   * @default No path condition
+   * @default - No path condition.
    */
   readonly pathPattern?: string;
 }
diff --git a/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/alb/application-listener.ts b/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/alb/application-listener.ts
index 1b11c5bb3ce46..3fec6822fbe80 100644
--- a/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/alb/application-listener.ts
+++ b/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/alb/application-listener.ts
@@ -16,33 +16,35 @@ export interface BaseApplicationListenerProps {
   /**
    * The protocol to use
    *
-   * @default Determined from port if known
+   * @default - Determined from port if known.
    */
   readonly protocol?: ApplicationProtocol;
 
   /**
    * The port on which the listener listens for requests.
    *
-   * @default Determined from protocol if known
+   * @default - Determined from protocol if known.
    */
   readonly port?: number;
 
   /**
    * The certificates to use on this listener
+   *
+   * @default - No certificates.
    */
   readonly certificateArns?: string[];
 
   /**
    * The security policy that defines which ciphers and protocols are supported.
    *
-   * @default the current predefined security policy.
+   * @default - The current predefined security policy.
    */
   readonly sslPolicy?: SslPolicy;
 
   /**
    * Default target groups to load balance to
    *
-   * @default None
+   * @default - None.
    */
   readonly defaultTargetGroups?: IApplicationTargetGroup[];
 
diff --git a/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/alb/application-target-group.ts b/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/alb/application-target-group.ts
index 1b416498c6de9..8df988f15f5a8 100644
--- a/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/alb/application-target-group.ts
+++ b/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/alb/application-target-group.ts
@@ -16,14 +16,14 @@ export interface ApplicationTargetGroupProps extends BaseTargetGroupProps {
   /**
    * The protocol to use
    *
-   * @default Determined from port if known
+   * @default - Determined from port if known.
    */
   readonly protocol?: ApplicationProtocol;
 
   /**
    * The port on which the listener listens for requests.
    *
-   * @default Determined from protocol if known
+   * @default - Determined from protocol if known.
    */
   readonly port?: number;
 
@@ -55,6 +55,8 @@ export interface ApplicationTargetGroupProps extends BaseTargetGroupProps {
    * Can be `Instance`, `IPAddress`, or any self-registering load balancing
    * target. If you use either `Instance` or `IPAddress` as targets, all
    * target must be of the same type.
+   *
+   * @default - No targets.
    */
   readonly targets?: IApplicationLoadBalancerTarget[];
 }
diff --git a/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/nlb/network-listener.ts b/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/nlb/network-listener.ts
index 6ae87fdf346c9..b84c92ca8deaa 100644
--- a/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/nlb/network-listener.ts
+++ b/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/nlb/network-listener.ts
@@ -17,22 +17,28 @@ export interface BaseNetworkListenerProps {
   /**
    * Default target groups to load balance to
    *
-   * @default None
+   * @default - None.
    */
   readonly defaultTargetGroups?: INetworkTargetGroup[];
 
   /**
    * Protocol for listener, expects TCP or TLS
+   *
+   * @default - TLS if certificates are provided. TCP otherwise.
    */
   readonly protocol?: Protocol;
 
   /**
    * Certificate list of ACM cert ARNs
+   *
+   * @default - No certificates.
    */
   readonly certificates?: INetworkListenerCertificateProps[];
 
   /**
    * SSL Policy
+   *
+   * @default - Current predefined security policy.
    */
   readonly sslPolicy?: SslPolicy;
 }
diff --git a/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/nlb/network-target-group.ts b/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/nlb/network-target-group.ts
index 441919078550d..c57385b0c104d 100644
--- a/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/nlb/network-target-group.ts
+++ b/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/nlb/network-target-group.ts
@@ -27,6 +27,8 @@ export interface NetworkTargetGroupProps extends BaseTargetGroupProps {
    * Can be `Instance`, `IPAddress`, or any self-registering load balancing
    * target. If you use either `Instance` or `IPAddress` as targets, all
    * target must be of the same type.
+   *
+   * @default - No targets.
    */
   readonly targets?: INetworkLoadBalancerTarget[];
 }
diff --git a/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/shared/base-load-balancer.ts b/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/shared/base-load-balancer.ts
index ff1f813273967..57dc5634f1cad 100644
--- a/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/shared/base-load-balancer.ts
+++ b/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/shared/base-load-balancer.ts
@@ -11,7 +11,7 @@ export interface BaseLoadBalancerProps {
   /**
    * Name of the load balancer
    *
-   * @default Automatically generated name
+   * @default - Automatically generated name.
    */
   readonly loadBalancerName?: string;
 
@@ -30,7 +30,7 @@ export interface BaseLoadBalancerProps {
   /**
    * Where in the VPC to place the load balancer
    *
-   * @default Public subnets if internetFacing, otherwise private subnets
+   * @default - Public subnets if internetFacing, otherwise private subnets.
    */
   readonly vpcSubnets?: ec2.SubnetSelection;
 
diff --git a/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/shared/base-target-group.ts b/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/shared/base-target-group.ts
index 821d65ecc3a2d..63857f0a3c62c 100644
--- a/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/shared/base-target-group.ts
+++ b/packages/@aws-cdk/aws-elasticloadbalancingv2/lib/shared/base-target-group.ts
@@ -15,7 +15,7 @@ export interface BaseTargetGroupProps {
    * 32 characters, must contain only alphanumeric characters or hyphens, and
    * must not begin or end with a hyphen.
    *
-   * @default Automatically generated
+   * @default - Automatically generated.
    */
   readonly targetGroupName?: string;
 
@@ -36,7 +36,7 @@ export interface BaseTargetGroupProps {
   /**
    * Health check configuration
    *
-   * @default No health check
+   * @default - None.
    */
   readonly healthCheck?: HealthCheck;
 
@@ -47,7 +47,7 @@ export interface BaseTargetGroupProps {
    * register targets to the TargetGroup in the CDK app, the TargetType is
    * determined automatically.
    *
-   * @default Determined automatically
+   * @default - Determined automatically.
    */
   readonly targetType?: TargetType;
 }
diff --git a/packages/@aws-cdk/aws-events/lib/rule.ts b/packages/@aws-cdk/aws-events/lib/rule.ts
index b70e6cdfa2453..152657993cee0 100644
--- a/packages/@aws-cdk/aws-events/lib/rule.ts
+++ b/packages/@aws-cdk/aws-events/lib/rule.ts
@@ -8,19 +8,23 @@ import { mergeEventPattern } from './util';
 export interface RuleProps {
   /**
    * A description of the rule's purpose.
+   *
+   * @default - No description.
    */
   readonly description?: string;
 
   /**
-   * A name for the rule. If you don't specify a name, AWS CloudFormation
-   * generates a unique physical ID and uses that ID for the rule name. For
-   * more information, see Name Type.
+   * A name for the rule.
+   *
+   * @default - AWS CloudFormation generates a unique physical ID and uses that ID
+   * for the rule name. For more information, see Name Type.
    */
   readonly ruleName?: string;
 
   /**
    * Indicates whether the rule is enabled.
-   * @default Rule is enabled
+   *
+   * @default true
    */
   readonly enabled?: boolean;
 
@@ -32,6 +36,8 @@ export interface RuleProps {
    * @see http://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html
    *
    * You must specify this property, the `eventPattern` property, or both.
+   *
+   * @default - None.
    */
   readonly scheduleExpression?: string;
 
@@ -47,6 +53,8 @@ export interface RuleProps {
    * `addEventPattern`), the `scheduleExpression` property, or both. The
    * method `addEventPattern` can be used to add filter values to the event
    * pattern.
+   *
+   * @default - None.
    */
   readonly eventPattern?: EventPattern;
 
@@ -55,6 +63,8 @@ export interface RuleProps {
    *
    * Input will be the full matched event. If you wish to specify custom
    * target input, use `addTarget(target[, inputOptions])`.
+   *
+   * @default - No targets.
    */
   readonly targets?: IRuleTarget[];
 }
diff --git a/packages/@aws-cdk/aws-iam/lib/group.ts b/packages/@aws-cdk/aws-iam/lib/group.ts
index 96a3e8404b7a8..568db5545b708 100644
--- a/packages/@aws-cdk/aws-iam/lib/group.ts
+++ b/packages/@aws-cdk/aws-iam/lib/group.ts
@@ -36,7 +36,8 @@ export interface GroupProps {
 
   /**
    * A list of ARNs for managed policies associated with group.
-   * @default No managed policies.
+   *
+   * @default - No managed policies.
    */
   readonly managedPolicyArns?: any[];
 
@@ -44,6 +45,8 @@ export interface GroupProps {
    * The path to the group. For more information about paths, see [IAM
    * Identifiers](http://docs.aws.amazon.com/IAM/latest/UserGuide/index.html?Using_Identifiers.html)
    * in the IAM User Guide.
+   *
+   * @default /
    */
   readonly path?: string;
 }
diff --git a/packages/@aws-cdk/aws-iam/lib/policy.ts b/packages/@aws-cdk/aws-iam/lib/policy.ts
index 415cc4ded027b..eb4f199024d86 100644
--- a/packages/@aws-cdk/aws-iam/lib/policy.ts
+++ b/packages/@aws-cdk/aws-iam/lib/policy.ts
@@ -19,32 +19,40 @@ export interface PolicyProps {
    * specify unique names. For example, if you specify a list of policies for
    * an IAM role, each policy must have a unique name.
    *
-   * @default Uses the logical ID of the policy resource, which is ensured to
-   *      be unique within the stack.
+   * @default - Uses the logical ID of the policy resource, which is ensured
+   * to be unique within the stack.
    */
   readonly policyName?: string;
 
   /**
    * Users to attach this policy to.
    * You can also use `attachToUser(user)` to attach this policy to a user.
+   *
+   * @default - No users.
    */
   readonly users?: IUser[];
 
   /**
    * Roles to attach this policy to.
    * You can also use `attachToRole(role)` to attach this policy to a role.
+   *
+   * @default - No roles.
    */
   readonly roles?: IRole[];
 
   /**
    * Groups to attach this policy to.
    * You can also use `attachToGroup(group)` to attach this policy to a group.
+   *
+   * @default - No groups.
    */
   readonly groups?: IGroup[];
 
   /**
    * Initial set of permissions to add to this policy document.
    * You can also use `addPermission(statement)` to add permissions later.
+   *
+   * @default - No statements.
    */
   readonly statements?: PolicyStatement[];
 }
diff --git a/packages/@aws-cdk/aws-iam/lib/role.ts b/packages/@aws-cdk/aws-iam/lib/role.ts
index 272be08adfb95..f1dd454ecbc12 100644
--- a/packages/@aws-cdk/aws-iam/lib/role.ts
+++ b/packages/@aws-cdk/aws-iam/lib/role.ts
@@ -30,7 +30,8 @@ export interface RoleProps {
   /**
    * A list of ARNs for managed policies associated with this role.
    * You can add managed policies later using `attachManagedPolicy(arn)`.
-   * @default No managed policies.
+   *
+   * @default - No managed policies.
    */
   readonly managedPolicyArns?: string[];
 
@@ -39,21 +40,22 @@ export interface RoleProps {
    * created with the role, whereas those added by ``addToPolicy`` are added
    * using a separate CloudFormation resource (allowing a way around circular
    * dependencies that could otherwise be introduced).
-   * @default No policy is inlined in the Role resource.
+   *
+   * @default - No policy is inlined in the Role resource.
    */
   readonly inlinePolicies?: { [name: string]: PolicyDocument };
 
   /**
    * The path associated with this role. For information about IAM paths, see
    * Friendly Names and Paths in IAM User Guide.
+   *
+   * @default /
    */
   readonly path?: string;
 
   /**
    * A name for the IAM role. For valid values, see the RoleName parameter for
-   * the CreateRole action in the IAM API Reference. If you don't specify a
-   * name, AWS CloudFormation generates a unique physical ID and uses that ID
-   * for the group name.
+   * the CreateRole action in the IAM API Reference.
    *
    * IMPORTANT: If you specify a name, you cannot perform updates that require
    * replacement of this resource. You can perform updates that require no or
@@ -62,14 +64,16 @@ export interface RoleProps {
    * If you specify a name, you must specify the CAPABILITY_NAMED_IAM value to
    * acknowledge your template's capabilities. For more information, see
    * Acknowledging IAM Resources in AWS CloudFormation Templates.
+   *
+   * @default - AWS CloudFormation generates a unique physical ID and uses that ID
+   * for the group name.
    */
   readonly roleName?: string;
 
   /**
    * The maximum session duration (in seconds) that you want to set for the
-   * specified role. If you do not specify a value for this setting, the
-   * default maximum of one hour is applied. This setting can have a value
-   * from 1 hour (3600sec) to 12 (43200sec) hours.
+   * specified role. This setting can have a value from 1 hour (3600sec) to
+   * 12 (43200sec) hours.
    *
    * Anyone who assumes the role from the AWS CLI or API can use the
    * DurationSeconds API parameter or the duration-seconds CLI parameter to
@@ -83,6 +87,8 @@ export interface RoleProps {
    * but does not apply when you use those operations to create a console URL.
    *
    * @link https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html
+   *
+   * @default 3600 (1 hour)
    */
   readonly maxSessionDurationSec?: number;
 }
diff --git a/packages/@aws-cdk/aws-iam/lib/user.ts b/packages/@aws-cdk/aws-iam/lib/user.ts
index f0e1d9ac9f6eb..dcf259ec3af2c 100644
--- a/packages/@aws-cdk/aws-iam/lib/user.ts
+++ b/packages/@aws-cdk/aws-iam/lib/user.ts
@@ -17,19 +17,24 @@ export interface UserProps {
   /**
    * Groups to add this user to. You can also use `addToGroup` to add this
    * user to a group.
+   *
+   * @default - No groups.
    */
   readonly groups?: IGroup[];
 
   /**
    * A list of ARNs for managed policies attacherd to this user.
    * You can use `addManagedPolicy(arn)` to attach a managed policy to this user.
-   * @default No managed policies.
+   *
+   * @default - No managed policies.
    */
   readonly managedPolicyArns?: any[];
 
   /**
    * The path for the user name. For more information about paths, see IAM
    * Identifiers in the IAM User Guide.
+   *
+   * @default /
    */
   readonly path?: string;
 
diff --git a/packages/@aws-cdk/aws-kms/lib/key.ts b/packages/@aws-cdk/aws-kms/lib/key.ts
index dda2977bdab18..0dff0c6cf1ab0 100644
--- a/packages/@aws-cdk/aws-kms/lib/key.ts
+++ b/packages/@aws-cdk/aws-kms/lib/key.ts
@@ -141,25 +141,29 @@ export interface KeyProps {
   /**
    * A description of the key. Use a description that helps your users decide
    * whether the key is appropriate for a particular task.
+   *
+   * @default - No description.
    */
   readonly description?: string;
 
   /**
    * Indicates whether AWS KMS rotates the key.
+   *
    * @default false
    */
   readonly enableKeyRotation?: boolean;
 
   /**
    * Indicates whether the key is available for use.
-   * @default Key is enabled
+   *
+   * @default - Key is enabled.
    */
   readonly enabled?: boolean;
 
   /**
    * Custom policy document to attach to the KMS key.
    *
-   * @default A policy document with permissions for the account root to
+   * @default - A policy document with permissions for the account root to
    * administer the key will be created.
    */
   readonly policy?: PolicyDocument;
diff --git a/packages/@aws-cdk/aws-lambda/lib/event-source-mapping.ts b/packages/@aws-cdk/aws-lambda/lib/event-source-mapping.ts
index 073900ab07eec..cd71bfa79fb99 100644
--- a/packages/@aws-cdk/aws-lambda/lib/event-source-mapping.ts
+++ b/packages/@aws-cdk/aws-lambda/lib/event-source-mapping.ts
@@ -17,7 +17,7 @@ export interface EventSourceMappingOptions {
    *
    * Valid Range: Minimum value of 1. Maximum value of 10000.
    *
-   * @default The default for Amazon Kinesis and Amazon DynamoDB is 100 records.
+   * @default - Amazon Kinesis and Amazon DynamoDB is 100 records.
    * Both the default and maximum for Amazon SQS are 10 messages.
    */
   readonly batchSize?: number;
@@ -34,6 +34,8 @@ export interface EventSourceMappingOptions {
    * start reading.
    *
    * @see https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetShardIterator.html#Kinesis-GetShardIterator-request-ShardIteratorType
+   *
+   * @default - Required for Amazon Kinesis and Amazon DynamoDB Streams sources.
    */
   readonly startingPosition?: StartingPosition
 }
diff --git a/packages/@aws-cdk/aws-lambda/lib/function.ts b/packages/@aws-cdk/aws-lambda/lib/function.ts
index ad7a3ec39d373..ee499a4b56dd0 100644
--- a/packages/@aws-cdk/aws-lambda/lib/function.ts
+++ b/packages/@aws-cdk/aws-lambda/lib/function.ts
@@ -43,6 +43,8 @@ export interface FunctionProps {
 
   /**
    * A description of the function.
+   *
+   * @default - No description.
    */
   readonly description?: string;
 
@@ -62,7 +64,7 @@ export interface FunctionProps {
    * the function. Because the execution time affects cost, set this value
    * based on the function's expected execution time.
    *
-   * @default 3 seconds.
+   * @default 3
    */
   readonly timeout?: number;
 
@@ -71,6 +73,8 @@ export interface FunctionProps {
    * functions. Use environment variables to apply configuration changes, such
    * as test and production environment configurations, without changing your
    * Lambda function source code.
+   *
+   * @default - No environment variables.
    */
   readonly environment?: { [key: string]: any };
 
@@ -82,9 +86,10 @@ export interface FunctionProps {
   readonly runtime: Runtime;
 
   /**
-   * A name for the function. If you don't specify a name, AWS CloudFormation
-   * generates a unique physical ID and uses that ID for the function's name.
-   * For more information, see Name Type.
+   * A name for the function.
+   *
+   * @default - AWS CloudFormation generates a unique physical ID and uses that
+   * ID for the function's name. For more information, see Name Type.
    */
   readonly functionName?: string;
 
@@ -94,7 +99,7 @@ export interface FunctionProps {
    * power. For more information, see Resource Model in the AWS Lambda
    * Developer Guide.
    *
-   * @default The default value is 128 MB
+   * @default 128
    */
   readonly memorySize?: number;
 
@@ -102,6 +107,8 @@ export interface FunctionProps {
    * Initial policy statements to add to the created Lambda Role.
    *
    * You can call `addToRolePolicy` to the created lambda to add statements post creation.
+   *
+   * @default - No policy statements are added to the created Lambda role.
    */
   readonly initialPolicy?: iam.PolicyStatement[];
 
@@ -112,7 +119,7 @@ export interface FunctionProps {
    * It controls the permissions that the function will have. The Role must
    * be assumable by the 'lambda.amazonaws.com' service principal.
    *
-   * @default a unique role will be generated for this lambda function.
+   * @default - A unique role will be generated for this lambda function.
    * Both supplied and generated roles can always be changed by calling `addToRolePolicy`.
    */
   readonly role?: iam.IRole;
@@ -121,6 +128,8 @@ export interface FunctionProps {
    * VPC network to place Lambda network interfaces
    *
    * Specify this if the Lambda function needs to access resources in a VPC.
+   *
+   * @default - Function is not placed within a VPC.
    */
   readonly vpc?: ec2.IVpc;
 
@@ -130,7 +139,7 @@ export interface FunctionProps {
    * Only used if 'vpc' is supplied. Note: internet access for Lambdas
    * requires a NAT gateway, so picking Public subnets is not allowed.
    *
-   * @default All private subnets
+   * @default - Private subnets.
    */
   readonly vpcSubnets?: ec2.SubnetSelection;
 
@@ -139,7 +148,7 @@ export interface FunctionProps {
    *
    * Only used if 'vpc' is supplied.
    *
-   * @default If the function is placed within a VPC and a security group is
+   * @default - If the function is placed within a VPC and a security group is
    * not specified, a dedicated security group will be created for this
    * function.
    */
@@ -159,21 +168,21 @@ export interface FunctionProps {
    * Enabled DLQ. If `deadLetterQueue` is undefined,
    * an SQS queue with default options will be defined for your Function.
    *
-   * @default false unless `deadLetterQueue` is set, which implies DLQ is enabled
+   * @default - false unless `deadLetterQueue` is set, which implies DLQ is enabled.
    */
   readonly deadLetterQueueEnabled?: boolean;
 
   /**
    * The SQS queue to use if DLQ is enabled.
    *
-   * @default SQS queue with 14 day retention period if `deadLetterQueueEnabled` is `true`
+   * @default - SQS queue with 14 day retention period if `deadLetterQueueEnabled` is `true`
    */
   readonly deadLetterQueue?: sqs.IQueue;
 
   /**
    * Enable AWS X-Ray Tracing for Lambda Function.
    *
-   * @default undefined X-Ray tracing disabled
+   * @default Tracing.Disabled
    */
   readonly tracing?: Tracing;
 
@@ -182,14 +191,14 @@ export interface FunctionProps {
    * additional code during initialization in the form of layers. Layers are packages of libraries or other dependencies
    * that can be used by mulitple functions.
    *
-   * @default no layers
+   * @default - No layers.
    */
   readonly layers?: ILayerVersion[];
 
   /**
    * The maximum of concurrent executions you want to reserve for the function.
    *
-   * @default no specific limit - account limit
+   * @default - No specific limit - account limit.
    * @see https://docs.aws.amazon.com/lambda/latest/dg/concurrent-executions.html
    */
   readonly reservedConcurrentExecutions?: number;
@@ -198,6 +207,8 @@ export interface FunctionProps {
    * Event sources for this function.
    *
    * You can also add event sources using `addEventSource`.
+   *
+   * @default - No event sources.
    */
   readonly events?: IEventSource[];
 
@@ -206,7 +217,7 @@ export interface FunctionProps {
    * this property, unsetting it doesn't remove the log retention policy. To
    * remove the retention policy, set the value to `Infinity`.
    *
-   * @default logs never expire
+   * @default - Logs never expire.
    */
   readonly logRetentionDays?: logs.RetentionDays;
 }
diff --git a/packages/@aws-cdk/aws-lambda/lib/layers.ts b/packages/@aws-cdk/aws-lambda/lib/layers.ts
index 6296e28dc2b29..71f4af437aca4 100644
--- a/packages/@aws-cdk/aws-lambda/lib/layers.ts
+++ b/packages/@aws-cdk/aws-lambda/lib/layers.ts
@@ -5,9 +5,9 @@ import { Runtime } from './runtime';
 
 export interface LayerVersionProps {
   /**
-   * The runtimes that this layer is compatible with.
+   * The runtimes compatible with this Layer.
    *
-   * @default All runtimes are supported
+   * @default - All runtimes are supported.
    */
   readonly compatibleRuntimes?: Runtime[];
 
@@ -18,19 +18,22 @@ export interface LayerVersionProps {
 
   /**
    * The description the this Lambda Layer.
+   *
+   * @default - No description.
    */
   readonly description?: string;
 
   /**
    * The SPDX licence identifier or URL to the license file for this layer.
    *
-   * @default no license information will be recorded.
+   * @default - No license information will be recorded.
    */
   readonly license?: string;
 
   /**
    * The name of the layer.
-   * @default a name will be generated.
+   *
+   * @default - A name will be generated.
    */
   readonly name?: string;
 }
@@ -44,6 +47,8 @@ export interface ILayerVersion extends IResource {
 
   /**
    * The runtimes compatible with this Layer.
+   *
+   * @default Runtime.All
    */
   readonly compatibleRuntimes?: Runtime[];
 
diff --git a/packages/@aws-cdk/aws-quickstarts/package.json b/packages/@aws-cdk/aws-quickstarts/package.json
index 04963f8cb7f79..1f0b0f31492a9 100644
--- a/packages/@aws-cdk/aws-quickstarts/package.json
+++ b/packages/@aws-cdk/aws-quickstarts/package.json
@@ -75,5 +75,10 @@
   },
   "engines": {
     "node": ">= 8.10.0"
+  },
+  "awslint": {
+    "exclude": [
+      "props-default-doc"
+    ]
   }
 }
diff --git a/packages/@aws-cdk/aws-rds/lib/cluster-parameter-group.ts b/packages/@aws-cdk/aws-rds/lib/cluster-parameter-group.ts
index beddc616a74e0..1ca9c92b14d31 100644
--- a/packages/@aws-cdk/aws-rds/lib/cluster-parameter-group.ts
+++ b/packages/@aws-cdk/aws-rds/lib/cluster-parameter-group.ts
@@ -35,6 +35,8 @@ export interface ClusterParameterGroupProps {
 
   /**
    * The parameters in this parameter group
+   *
+   * @default - No parameters.
    */
   readonly parameters?: Parameters;
 }
diff --git a/packages/@aws-cdk/aws-rds/lib/cluster.ts b/packages/@aws-cdk/aws-rds/lib/cluster.ts
index 1d61342f62273..13c502b1df04d 100644
--- a/packages/@aws-cdk/aws-rds/lib/cluster.ts
+++ b/packages/@aws-cdk/aws-rds/lib/cluster.ts
@@ -39,20 +39,25 @@ export interface DatabaseClusterProps {
 
   /**
    * Backup settings
+   *
+   * @default - Backup retention period for automated backups is 1 day.
+   * Backup preferred window is set to a 30-minute window selected at random from an
+   * 8-hour block of time for each AWS Region, occurring on a random day of the week.
+   * @see https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_UpgradeDBInstance.Maintenance.html#AdjustingTheMaintenanceWindow.Aurora
    */
   readonly backup?: BackupProps;
 
   /**
    * What port to listen on
    *
-   * If not supplied, the default for the engine is used.
+   * @default - The default for the engine is used.
    */
   readonly port?: number;
 
   /**
    * An optional identifier for the cluster
    *
-   * If not supplied, a name is automatically generated.
+   * @default - A name is automatically generated.
    */
   readonly clusterIdentifier?: string;
 
@@ -61,14 +66,15 @@ export interface DatabaseClusterProps {
    *
    * Every replica is named by appending the replica number to this string, 1-based.
    *
-   * If not given, the clusterIdentifier is used with the word "Instance" appended.
-   *
-   * If clusterIdentifier is also not given, the identifier is automatically generated.
+   * @default - clusterIdentifier is used with the word "Instance" appended.
+   * If clusterIdentifier is not provided, the identifier is automatically generated.
    */
   readonly instanceIdentifierBase?: string;
 
   /**
    * Name of a database which is automatically created inside the cluster
+   *
+   * @default - Database is not created in cluster.
    */
   readonly defaultDatabaseName?: string;
 
@@ -83,7 +89,7 @@ export interface DatabaseClusterProps {
    * The KMS key for storage encryption. If specified `storageEncrypted`
    * will be set to `true`.
    *
-   * @default default master key
+   * @default - default master key.
    */
   readonly kmsKey?: kms.IKey;
 
@@ -93,13 +99,17 @@ export interface DatabaseClusterProps {
    * Must be at least 30 minutes long.
    *
    * Example: '01:00-02:00'
+   *
+   * @default - 30-minute window selected at random from an 8-hour block of time for
+   * each AWS Region, occurring on a random day of the week.
+   * @see https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_UpgradeDBInstance.Maintenance.html#AdjustingTheMaintenanceWindow.Aurora
    */
   readonly preferredMaintenanceWindow?: string;
 
   /**
    * Additional parameters to pass to the database engine
    *
-   * @default No parameter group
+   * @default - No parameter group.
    */
   readonly parameterGroup?: IClusterParameterGroup;
 
@@ -107,7 +117,7 @@ export interface DatabaseClusterProps {
    * The CloudFormation policy to apply when the cluster and its instances
    * are removed from the stack or replaced during an update.
    *
-   * @default Retain
+   * @default - Retain cluster.
    */
   readonly deleteReplacePolicy?: DeletionPolicy
 }
diff --git a/packages/@aws-cdk/aws-rds/lib/props.ts b/packages/@aws-cdk/aws-rds/lib/props.ts
index e25b0d63910c4..869b1ec85371a 100644
--- a/packages/@aws-cdk/aws-rds/lib/props.ts
+++ b/packages/@aws-cdk/aws-rds/lib/props.ts
@@ -41,6 +41,11 @@ export interface InstanceProps {
 
 /**
  * Backup configuration for RDS databases
+ *
+ * @default - The retention period for automated backups is 1 day.
+ * The preferred backup window will be a 30-minute window selected at random
+ * from an 8-hour block of time for each AWS Region.
+ * @see https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_UpgradeDBInstance.Maintenance.html#AdjustingTheMaintenanceWindow.Aurora
  */
 export interface BackupProps {
 
diff --git a/packages/@aws-cdk/aws-rds/lib/rotation-single-user.ts b/packages/@aws-cdk/aws-rds/lib/rotation-single-user.ts
index 2340ac049c2d6..c877d3c4044cc 100644
--- a/packages/@aws-cdk/aws-rds/lib/rotation-single-user.ts
+++ b/packages/@aws-cdk/aws-rds/lib/rotation-single-user.ts
@@ -96,7 +96,7 @@ export interface RotationSingleUserProps extends RotationSingleUserOptions {
   /**
    * The database engine. Either `serverlessApplicationLocation` or `engine` must be specified.
    *
-   * @default no engine specified
+   * @default - No engine specified.
    */
   readonly engine?: DatabaseEngine;
 
@@ -108,7 +108,7 @@ export interface RotationSingleUserProps extends RotationSingleUserOptions {
   /**
    * The type of subnets in the VPC where the Lambda rotation function will run.
    *
-   * @default private subnets
+   * @default - Private subnets.
    */
   readonly vpcSubnets?: ec2.SubnetSelection;
 
diff --git a/packages/@aws-cdk/aws-s3/lib/bucket.ts b/packages/@aws-cdk/aws-s3/lib/bucket.ts
index eb17df7b618c4..9166020e24a43 100644
--- a/packages/@aws-cdk/aws-s3/lib/bucket.ts
+++ b/packages/@aws-cdk/aws-s3/lib/bucket.ts
@@ -575,7 +575,7 @@ export interface BucketProps {
    * If you choose KMS, you can specify a KMS key via `encryptionKey`. If
    * encryption key is not specified, a key will automatically be created.
    *
-   * @default Unencrypted
+   * @default BucketEncryption.Unencrypted
    */
   readonly encryption?: BucketEncryption;
 
@@ -586,22 +586,22 @@ export interface BucketProps {
    * An error will be emitted if encryption is set to "Unencrypted" or
    * "Managed".
    *
-   * @default If encryption is set to "Kms" and this property is undefined, a
-   * new KMS key will be created and associated with this bucket.
+   * @default - If encryption is set to "Kms" and this property is undefined,
+   * a new KMS key will be created and associated with this bucket.
    */
   readonly encryptionKey?: kms.IKey;
 
   /**
    * Physical name of this bucket.
    *
-   * @default Assigned by CloudFormation (recommended)
+   * @default - Assigned by CloudFormation (recommended).
    */
   readonly bucketName?: string;
 
   /**
    * Policy to apply when the bucket is removed from this stack.
    *
-   * @default The bucket will be orphaned
+   * @default - The bucket will be orphaned.
    */
   readonly removalPolicy?: RemovalPolicy;
 
@@ -615,25 +615,31 @@ export interface BucketProps {
   /**
    * Rules that define how Amazon S3 manages objects during their lifetime.
    *
-   * @default No lifecycle rules
+   * @default - No lifecycle rules.
    */
   readonly lifecycleRules?: LifecycleRule[];
 
   /**
    * The name of the index document (e.g. "index.html") for the website. Enables static website
    * hosting for this bucket.
+   *
+   * @default - No index document.
    */
   readonly websiteIndexDocument?: string;
 
   /**
    * The name of the error document (e.g. "404.html") for the website.
    * `websiteIndexDocument` must also be set if this is set.
+   *
+   * @default - No error document.
    */
   readonly websiteErrorDocument?: string;
 
   /**
    * Grants public read access to all objects in the bucket.
    * Similar to calling `bucket.grantPublicAccess()`
+   *
+   * @default false
    */
   readonly publicReadAccess?: boolean;
 
@@ -641,6 +647,9 @@ export interface BucketProps {
    * The block public access configuration of this bucket.
    *
    * @see https://docs.aws.amazon.com/AmazonS3/latest/dev/access-control-block-public-access.html
+   *
+   * @default false New buckets and objects don't allow public access, but users can modify bucket
+   * policies or object permissions to allow public access.
    */
   readonly blockPublicAccess?: BlockPublicAccess;
 
@@ -648,6 +657,8 @@ export interface BucketProps {
    * The metrics configuration of this bucket.
    *
    * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket-metricsconfiguration.html
+   *
+   * @default - No metrics configuration.
    */
   readonly metrics?: BucketMetrics[];
 }
diff --git a/packages/@aws-cdk/aws-secretsmanager/lib/secret.ts b/packages/@aws-cdk/aws-secretsmanager/lib/secret.ts
index a626de80eaf2f..09ac282e02807 100644
--- a/packages/@aws-cdk/aws-secretsmanager/lib/secret.ts
+++ b/packages/@aws-cdk/aws-secretsmanager/lib/secret.ts
@@ -52,21 +52,23 @@ export interface ISecret extends IResource {
 export interface SecretProps {
   /**
    * An optional, human-friendly description of the secret.
+   *
+   * @default - No description.
    */
   readonly description?: string;
 
   /**
    * The customer-managed encryption key to use for encrypting the secret value.
    *
-   * @default a default KMS key for the account and region is used.
+   * @default - A default KMS key for the account and region is used.
    */
   readonly encryptionKey?: kms.IKey;
 
   /**
    * Configuration for how to generate a secret value.
    *
-   * @default 32 characters with upper-case letters, lower-case letters, punctuation and numbers (at least one from each
-   *          category), per the default values of ``SecretStringGenerator``.
+   * @default - 32 characters with upper-case letters, lower-case letters, punctuation and numbers (at least one from each
+   * category), per the default values of ``SecretStringGenerator``.
    */
   readonly generateSecretString?: SecretStringGenerator;
 
@@ -74,7 +76,7 @@ export interface SecretProps {
    * A name for the secret. Note that deleting secrets from SecretsManager does not happen immediately, but after a 7 to
    * 30 days blackout period. During that period, it is not possible to create another secret that shares the same name.
    *
-   * @default - a name is generated by CloudFormation.
+   * @default - A name is generated by CloudFormation.
    */
   readonly name?: string;
 }
diff --git a/packages/@aws-cdk/aws-ses/lib/receipt-rule-set.ts b/packages/@aws-cdk/aws-ses/lib/receipt-rule-set.ts
index 395e37746d8a0..5b2aa4d3875b9 100644
--- a/packages/@aws-cdk/aws-ses/lib/receipt-rule-set.ts
+++ b/packages/@aws-cdk/aws-ses/lib/receipt-rule-set.ts
@@ -26,13 +26,15 @@ export interface ReceiptRuleSetProps {
   /**
    * The name for the receipt rule set.
    *
-   * @default a CloudFormation generated name
+   * @default - A CloudFormation generated name.
    */
   readonly name?: string;
 
   /**
    * The list of rules to add to this rule set. Rules are added in the same
    * order as they appear in the list.
+   *
+   * @default - No rules are added to the rule set.
    */
   readonly rules?: ReceiptRuleOptions[]
 
diff --git a/packages/@aws-cdk/aws-ses/lib/receipt-rule.ts b/packages/@aws-cdk/aws-ses/lib/receipt-rule.ts
index 06ce393aa93a1..73b929eafe3c2 100644
--- a/packages/@aws-cdk/aws-ses/lib/receipt-rule.ts
+++ b/packages/@aws-cdk/aws-ses/lib/receipt-rule.ts
@@ -38,13 +38,15 @@ export interface ReceiptRuleOptions {
    * An ordered list of actions to perform on messages that match at least
    * one of the recipient email addresses or domains specified in the
    * receipt rule.
+   *
+   * @default - No actions.
    */
   readonly actions?: IReceiptRuleAction[];
 
   /**
    * An existing rule after which the new rule will be placed.
    *
-   * @default the new rule is inserted at the beginning of the rule list
+   * @default - The new rule is inserted at the beginning of the rule list.
    */
   readonly after?: IReceiptRule;
 
@@ -58,28 +60,29 @@ export interface ReceiptRuleOptions {
   /**
    * The name for the rule
    *
-   * @default a CloudFormation generated name
+   * @default - A CloudFormation generated name.
    */
   readonly name?: string;
 
   /**
    * The recipient domains and email addresses that the receipt rule applies to.
    *
-   * @default match all recipients under all verified domains.
+   * @default - Match all recipients under all verified domains.
    */
   readonly recipients?: string[];
 
   /**
-   * Wheter to scan for spam and viruses.
+   * Whether to scan for spam and viruses.
    *
    * @default false
    */
   readonly scanEnabled?: boolean;
 
   /**
-   * The TLS policy
+   * Whether Amazon SES should require that incoming email is delivered over a
+   * connection encrypted with Transport Layer Security (TLS).
    *
-   * @default Optional
+   * @default - Optional which will not check for TLS.
    */
   readonly tlsPolicy?: TlsPolicy;
 }
diff --git a/packages/@aws-cdk/cdk/lib/cfn-condition.ts b/packages/@aws-cdk/cdk/lib/cfn-condition.ts
index 94714877b53b1..4b97b48467f61 100644
--- a/packages/@aws-cdk/cdk/lib/cfn-condition.ts
+++ b/packages/@aws-cdk/cdk/lib/cfn-condition.ts
@@ -3,6 +3,11 @@ import { Construct } from './construct';
 import { IResolveContext } from './token';
 
 export interface CfnConditionProps {
+  /**
+   * The expression that the condition will evaluate.
+   *
+   * @default - None.
+   */
   readonly expression?: ICfnConditionExpression;
 }
 
diff --git a/packages/@aws-cdk/cdk/lib/cfn-mapping.ts b/packages/@aws-cdk/cdk/lib/cfn-mapping.ts
index 7ec630bbf312c..a7e63805ac463 100644
--- a/packages/@aws-cdk/cdk/lib/cfn-mapping.ts
+++ b/packages/@aws-cdk/cdk/lib/cfn-mapping.ts
@@ -4,6 +4,16 @@ import { Fn } from './fn';
 import { Token } from './token';
 
 export interface CfnMappingProps {
+  /**
+   * Mapping of key to a set of corresponding set of named values.
+   * The key identifies a map of name-value pairs and must be unique within the mapping.
+   *
+   * For example, if you want to set values based on a region, you can create a mapping
+   * that uses the region name as a key and contains the values you want to specify for
+   * each specific region.
+   *
+   * @default - No mapping.
+   */
   readonly mapping?: { [k1: string]: { [k2: string]: any } };
 }
 
diff --git a/packages/@aws-cdk/cdk/lib/cfn-output.ts b/packages/@aws-cdk/cdk/lib/cfn-output.ts
index 813b0f78fce3a..46b462a625772 100644
--- a/packages/@aws-cdk/cdk/lib/cfn-output.ts
+++ b/packages/@aws-cdk/cdk/lib/cfn-output.ts
@@ -5,6 +5,8 @@ export interface CfnOutputProps {
   /**
    * A String type that describes the output value.
    * The description can be a maximum of 4 K in length.
+   *
+   * @default - No description.
    */
   readonly description?: string;
 
@@ -21,7 +23,7 @@ export interface CfnOutputProps {
    * To import the value from another stack, use `FnImportValue(export)`. You
    * can create an import value token by calling `output.makeImportValue()`.
    *
-   * @default Automatically allocate a name when `makeImportValue()`  is
+   * @default - Automatically allocate a name when `makeImportValue()` is
    * called.
    */
   readonly export?: string;
@@ -40,6 +42,8 @@ export interface CfnOutputProps {
    * A condition from the "Conditions" section to associate with this output
    * value. If the condition evaluates to `false`, this output value will not
    * be included in the stack.
+   *
+   * @default - No condition is associated with the output.
    */
   readonly condition?: CfnCondition;
 }
@@ -169,6 +173,8 @@ export interface StringListCfnOutputProps {
   /**
    * A String type that describes the output value.
    * The description can be a maximum of 4 K in length.
+   *
+   * @default - No description.
    */
   readonly description?: string;
 
@@ -207,6 +213,8 @@ export interface StringListCfnOutputProps {
    * A condition from the "Conditions" section to associate with this output
    * value. If the condition evaluates to `false`, this output value will not
    * be included in the stack.
+   *
+   * @default - None.
    */
   readonly condition?: CfnCondition;
 }
diff --git a/packages/@aws-cdk/cdk/lib/cfn-parameter.ts b/packages/@aws-cdk/cdk/lib/cfn-parameter.ts
index 2550b9671a1d2..cab3ccbc7eb87 100644
--- a/packages/@aws-cdk/cdk/lib/cfn-parameter.ts
+++ b/packages/@aws-cdk/cdk/lib/cfn-parameter.ts
@@ -12,16 +12,22 @@ export interface CfnParameterProps {
    * A value of the appropriate type for the template to use if no value is specified
    * when a stack is created. If you define constraints for the parameter, you must specify
    * a value that adheres to those constraints.
+   *
+   * @default - No default value for parameter.
    */
   readonly default?: any;
 
   /**
    * A regular expression that represents the patterns to allow for String types.
+   *
+   * @default - No constraints on patterns allowed for parameter.
    */
   readonly allowedPattern?: string;
 
   /**
    * An array containing the list of values allowed for the parameter.
+   *
+   * @default - No constraints on values allowed for parameter.
    */
   readonly allowedValues?: string[];
 
@@ -30,37 +36,51 @@ export interface CfnParameterProps {
    * For example, without a constraint description, a parameter that has an allowed
    * pattern of [A-Za-z0-9]+ displays the following error message when the user specifies
    * an invalid value:
+   *
+   * @default - No description with customized error message when user specifies invalid values.
    */
   readonly constraintDescription?: string;
 
   /**
    * A string of up to 4000 characters that describes the parameter.
+   *
+   * @default - No description for the parameter.
    */
   readonly description?: string;
 
   /**
    * An integer value that determines the largest number of characters you want to allow for String types.
+   *
+   * @default - None.
    */
   readonly maxLength?: number;
 
   /**
    * A numeric value that determines the largest numeric value you want to allow for Number types.
+   *
+   * @default - None.
    */
   readonly maxValue?: number;
 
   /**
    * An integer value that determines the smallest number of characters you want to allow for String types.
+   *
+   * @default - None.
    */
   readonly minLength?: number;
 
   /**
    * A numeric value that determines the smallest numeric value you want to allow for Number types.
+   *
+   * @default - None.
    */
   readonly minValue?: number;
 
   /**
    * Whether to mask the parameter value when anyone makes a call that describes the stack.
    * If you set the value to ``true``, the parameter value is masked with asterisks (``*****``).
+   *
+   * @default - Parameter values are not masked.
    */
   readonly noEcho?: boolean;
 }
diff --git a/packages/@aws-cdk/cdk/lib/cfn-resource.ts b/packages/@aws-cdk/cdk/lib/cfn-resource.ts
index e738818e49194..03222c1aae72d 100644
--- a/packages/@aws-cdk/cdk/lib/cfn-resource.ts
+++ b/packages/@aws-cdk/cdk/lib/cfn-resource.ts
@@ -17,6 +17,8 @@ export interface CfnResourceProps {
 
   /**
    * CloudFormation properties.
+   *
+   * @default - No resource properties.
    */
   readonly properties?: any;
 }
diff --git a/packages/@aws-cdk/cdk/lib/cfn-rule.ts b/packages/@aws-cdk/cdk/lib/cfn-rule.ts
index a663b78dc1bb3..bf41309eb0bbc 100644
--- a/packages/@aws-cdk/cdk/lib/cfn-rule.ts
+++ b/packages/@aws-cdk/cdk/lib/cfn-rule.ts
@@ -28,11 +28,15 @@ export interface CfnRuleProps {
   /**
    * If the rule condition evaluates to false, the rule doesn't take effect.
    * If the function in the rule condition evaluates to true, expressions in each assert are evaluated and applied.
+   *
+   * @default - Rule's assertions will always take effect.
    */
   readonly ruleCondition?: ICfnConditionExpression;
 
   /**
    * Assertions which define the rule.
+   *
+   * @default - No assertions for the rule.
    */
   readonly assertions?: RuleAssertion[];
 }
diff --git a/packages/@aws-cdk/cdk/lib/stack.ts b/packages/@aws-cdk/cdk/lib/stack.ts
index d8392af9aec31..63b9d5f367311 100644
--- a/packages/@aws-cdk/cdk/lib/stack.ts
+++ b/packages/@aws-cdk/cdk/lib/stack.ts
@@ -11,7 +11,7 @@ export interface StackProps {
   /**
    * The AWS environment (account/region) where this stack will be deployed.
    *
-   * If not supplied, the `default-account` and `default-region` context parameters will be
+   * @default - The `default-account` and `default-region` context parameters will be
    * used. If they are undefined, it will not be possible to deploy the stack.
    */
   readonly env?: Environment;
@@ -19,14 +19,14 @@ export interface StackProps {
   /**
    * Name to deploy the stack with
    *
-   * @default Derived from construct path
+   * @default - Derived from construct path.
    */
   readonly stackName?: string;
 
   /**
    * Strategy for logical ID generation
    *
-   * Optional. If not supplied, the HashedNamingScheme will be used.
+   * @default - The HashedNamingScheme will be used.
    */
   readonly namingScheme?: IAddressingScheme;
 
diff --git a/tools/awslint/lib/rules/construct.ts b/tools/awslint/lib/rules/construct.ts
index 4d80287fe79dc..19a484684776c 100644
--- a/tools/awslint/lib/rules/construct.ts
+++ b/tools/awslint/lib/rules/construct.ts
@@ -235,4 +235,21 @@ constructLinter.add({
       }
     }
   }
-});
\ No newline at end of file
+});
+
+constructLinter.add({
+  code: 'props-default-doc',
+  message: 'All optional props should have @default documentation',
+  eval: e => {
+    if (!e.ctx.propsType) { return; }
+    if (!e.ctx.hasPropsArgument) { return; }
+
+    // this rule only applies to L2 constructs
+    if (CoreTypes.isCfnResource(e.ctx.classType)) { return; }
+
+    for (const property of e.ctx.propsType.allProperties) {
+      if (!property.optional) { continue; }
+      e.assert(property.docs.docs.default !== undefined, `${e.ctx.propsFqn}.${property.name}`);
+    }
+  }
+  });
\ No newline at end of file