refactor: L2 constructs should include default docs for optional prop…

…s (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

@@ -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[];
 }

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;
 

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 || {};
 

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;
 }

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,45 +60,53 @@ 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;
 
   /**
    * 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;

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,24 +37,30 @@ 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;
 
   /**
    * 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-._~:/?#&=,]+.
+   *
+   * @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,50 +93,65 @@ export enum MethodLoggingLevel {
 export interface MethodDeploymentOptions {
   /**
    * Specifies whether Amazon CloudWatch metrics are enabled for this method.
+   *
    * @default false
    */
   readonly metricsEnabled?: boolean;
 
   /**
    * 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;

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;
 }