document GuStack

src/constructs/core/stack.ts

@@ -10,6 +10,33 @@ export interface GuStackProps extends StackProps {
   migratedFromCloudFormation?: boolean;
 }
 
+/**
+ * GuStack provides the `stack` and `stage` parameters to a template.
+ * It also takes the `app` in the constructor.
+ *
+ * GuStack will add the Stack, Stage and App tags to all resources.
+ *
+ * GuStack also adds the tag `X-Gu-CDK-Version`.
+ * This tag allows us to measure adoption of this library.
+ * It's value is the version of guardian/cdk being used, as defined in `package.json`.
+ * As a result, the change sets between version numbers will be fairly noisy,
+ * as all resources receive a tag update.
+ * It is recommended to upgrade the version of @guardian/cdk being used in two steps:
+ *   1. Bump the library, apply the tag updates
+ *   2. Make any other stack changes
+ *
+ * Typical usage is to extend GuStack:
+ *
+ * ```typescript
+ * class MyStack extends GuStack {
+ *   constructor(scope: App, id: string, props: GuStackProps) {
+ *     super(scope, id, props)
+ *   }
+ *
+ *   // add resources here
+ * }
+ * ```
+ */
 export class GuStack extends Stack {
   private readonly _stage: GuStageParameter;
   private readonly _stack: GuStackParameter;
@@ -29,6 +56,13 @@ export class GuStack extends Stack {
 
   migratedFromCloudFormation: boolean;
 
+  /**
+   * A helper function to add a tag to all resources in a stack.
+   * @param key the tag name
+   * @param value the value of the tag
+   * @param applyToLaunchedInstances whether or not to apply the tag to instances launched in an ASG.
+   * @protected
+   */
   protected addTag(key: string, value: string, applyToLaunchedInstances: boolean = true): void {
     Tags.of(this).add(key, value, { applyToLaunchedInstances });
   }