docs: Extend tsdoc requirements to everything in patterns/**

Expands use of:

https://github.com/guardian/eslint-plugin-tsdoc-required

The aim is to align our documentation style with AWS's own CDK
library - specifically that exported properties must be documented.

.eslintrc.js

@@ -34,5 +34,11 @@ module.exports = {
         "custom-rules/experimental-classes": 2,
       },
     },
+    {
+      files: ["src/patterns/**"], // Incremental rollout.
+      rules: {
+        "@guardian/tsdoc-required/tsdoc-required": 2,
+      }
+    }
   ],
 };

src/patterns/api-lambda.ts

@@ -16,7 +16,6 @@ export interface GuApiLambdaProps extends Omit<GuFunctionProps, "errorPercentage
    * [[`LambdaRestApiProps`]] to configure for the lambda.
    */
   api: ApiProps;
-
   /**
    * Alarm configuration for your API. For more details, see [[`ApiGatewayAlarms`]].
    *

src/patterns/api-multiple-lambdas.ts

@@ -6,9 +6,14 @@ import { GuApiGateway5xxPercentageAlarm } from "../constructs/cloudwatch/api-gat
 import type { AppIdentity, GuStack } from "../constructs/core";
 import type { GuLambdaFunction } from "../constructs/lambda";
 
-// https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
+/**
+ * See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
+ */
 export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "CONNECT" | "OPTIONS" | "TRACE" | "PATCH";
 
+/**
+ * API target props.
+ */
 export interface ApiTarget {
   /**
    * The path for the request (e.g. /test).
@@ -29,22 +34,20 @@ export interface ApiTarget {
 }
 
 /**
- * Configuration for an alarm based on the percentage of 5XX responses served by the API Gateway instance.
- *
- * For example:
- *
- * ```typescript
- * monitoringConfiguration: {
- *   snsTopicName: "my-topic-for-cloudwatch-alerts",
- *   http5xxAlarm: {
- *     tolerated5xxPercentage: <sensible_error_percentage_threshold>,
- *   }
- * }
- * ```
+ * Alarm props.
  */
 export interface ApiGatewayAlarms {
+  /**
+   * (SNS) Topic name where alarm notifications will be sent.
+   */
   snsTopicName: string;
+  /**
+   * Configuration the 5xx alarm.
+   */
   http5xxAlarm: Http5xxAlarmProps;
+  /**
+   * Internal flag - users of this library should ignore this setting.
+   */
   noMonitoring?: false;
 }
 

src/patterns/ec2-app/base.ts

@@ -1,4 +1,3 @@
-/* eslint "@guardian/tsdoc-required/tsdoc-required": 2 -- to begin rolling this out for public APIs. */
 import { Duration, Tags } from "aws-cdk-lib";
 import type { BlockDevice } from "aws-cdk-lib/aws-autoscaling";
 import { HealthCheck } from "aws-cdk-lib/aws-autoscaling";

src/patterns/scheduled-ecs-task.ts

@@ -6,34 +6,15 @@ import type { GuEcsTaskProps } from "../constructs/ecs";
 import { GuEcsTask } from "../constructs/ecs";
 import { GuAppAwareConstruct } from "../utils/mixin/app-aware-construct";
 
-/**
- * Configuration options for the [[`GuScheduledEcsTask`]] pattern.
- *
- * The `schedule` property determines when your task is invoked. For example, to invoke
- * the task every 5 minutes, use:
- * ```typescript
- * import { Schedule } from "aws-cdk-lib/aws-events";
- * import { Duration } from "aws-cdk-lib/core";
- *
- * const props = {
- *   // Other props here
- *   schedule: Schedule.rate(Duration.minutes(5)),
- * }
- * ```
- *
- * To invoke the task every weekday at 8am, use:
- * ```
- * import { Schedule } from "aws-cdk-lib/aws-events";
- *
- * const props = {
- *   // Other props here
- *   schedule: Schedule.expression("cron(0 8 ? * MON-FRI *)"),
- * }
- * ```
- * See [[`GuEcsTask`]] for details of other props
- *
- */
 export interface GuScheduledEcsTaskProps extends GuEcsTaskProps {
+  /**
+   * Schedule for the task.
+   *
+   * E.g.:
+   *
+   * - `Schedule.expression("cron(0 8 ? * MON-FRI *)")`
+   * - `Schedule.rate(Duration.minutes(5))`
+   */
   schedule: Schedule;
 }
 

src/patterns/scheduled-lambda.ts

@@ -6,55 +6,28 @@ import type { GuStack } from "../constructs/core";
 import { GuLambdaFunction } from "../constructs/lambda";
 import type { GuFunctionProps } from "../constructs/lambda";
 
-/**
- * Configuration options for the [[`GuScheduledLambda`]] pattern.
- *
- * For all lambda function configuration options, see [[`GuFunctionProps`]].
- *
- * The `schedule` property determines when your lambda is invoked. For example, to invoke
- * the lambda every 5 minutes, use:
- * ```typescript
- * import { Schedule } from "aws-cdk-lib/aws-events";
- * import { Duration } from "aws-cdk-lib/core";
- *
- * const props = {
- *   // Other props here
- *   rules: [{ schedule: Schedule.rate(Duration.minutes(5)) }],
- * }
- * ```
- *
- * To invoke the lambda every weekday at 8am, use:
- * ```
- * import { Schedule } from "aws-cdk-lib/aws-events";
- *
- * const props = {
- *   // Other props here
- *   rules: [{ schedule: Schedule.expression("cron(0 8 ? * MON-FRI *)") }],
- * }
- * ```
- *
- * It is advisable to configure an alarm based on the lambda's error percentage.
- * To do this, add the `monitoringConfiguration` property. The required properties for this are:
- *
- * ```typescript
- * monitoringConfiguration: {
- *   toleratedErrorPercentage: <sensible_error_percentage_threshold>,
- *   snsTopicName: "my-topic-for-cloudwatch-alerts",
- * }
- * ```
- * Other alarm properties (e.g. alarm name and description) will be pre-populated with sensible defaults.
- * For a full list of optional properties, see [[`GuLambdaErrorPercentageMonitoringProps`]].
- *
- * If your team do not use CloudWatch, it's possible to opt-out with the following configuration:
- * ```typescript
- *  monitoringConfiguration: { noMonitoring: true }
- * ```
- */
 export interface GuScheduledLambdaProps extends Omit<GuFunctionProps, "errorPercentageMonitoring"> {
+  /**
+   * Schedule(s) for the lambda task.
+   */
   rules: Array<{
+    /**
+     * E.g.:
+     *
+     * - `Schedule.expression("cron(0 8 ? * MON-FRI *)")`
+     * - `Schedule.rate(Duration.minutes(5))`
+     */
     schedule: Schedule;
+    /**
+     * Optional description.
+     */
     description?: string;
   }>;
+  /**
+   * Monitoring configuration for the lambda.
+   *
+   * Opting-out via the `NoMonitoring` type is supported but discouraged.
+   */
   monitoringConfiguration: NoMonitoring | GuLambdaErrorPercentageMonitoringProps;
 }