majiayu000 Documentation Standards
This project uses TSDoc (TypeScript Documentation) for all code documentation. TSDoc is the TypeScript-specific standard built on JSDoc.
Philosophy
Inline TSDoc provides quick reference for IDE tooltips. Comprehensive guides, tutorials, and detailed examples belong in /docs directories within each subpackage.
General Principles
- Every public API must have documentation
- Keep it concise - inline docs are for quick reference
- One example maximum per type/function (simple usage only)
- Link to related types with
{@link TypeName} - Tag visibility with
@public,@internal, or@private - Detailed guides go in /docs, not inline
Documentation Structure
For Type Properties
/** Brief one-line description. */
propertyName: string;
/** Optional property description. @defaultValue `default-value` */
optionalProperty?: number;
For Types/Interfaces
/**
* Brief description of what this type represents (1-2 sentences).
*
* @example
* ```typescript
* const example: MyType = {
* property: 'value',
* };
* ```
*
* @see {@link RelatedType} for related functionality
* @public
*/
export type MyType = {
/** Property description. */
property: string;
};
For Functions
/**
* Brief description of what this function does.
*
* @remarks
* Only include critical prerequisites or warnings here.
*
* @param paramName - Brief parameter description
* @returns Brief return description (only if needed)
*
* @example
* ```typescript
* const result = myFunction(param);
* ```
*
* @see {@link RelatedFunction} for related functionality
* @public
*/
export const myFunction = (paramName: string): ReturnType => {
// Implementation
};
Tag Reference
Required Tags
Description (No Tag)
The first paragraph is always the main description. Keep it brief (1-2 sentences).
/**
* Creates an Aurora PostgreSQL cluster with optimized settings.
*/
@param - Parameter Documentation
One-line description per parameter.
/**
* @param scope - The CDK construct scope
* @param id - Unique identifier for this construct
* @param props - Configuration properties
*/
@public / @internal / @private - API Visibility
Always tag the visibility.
/**
* Creates an Aurora cluster for production use.
* @public
*/
Optional Tags (Use Sparingly)
@remarks - Critical Information Only
Use only for critical prerequisites, warnings, or non-obvious behavior.
/**
* @remarks
* Requires VPC with at least 2 private subnets in different AZs.
*/
@returns - Return Value Description
Only include if the return value needs clarification beyond the type signature.
/**
* @returns The created cluster with monitoring enabled
*/
@example - Single Simple Example
One example maximum. Keep it simple and basic usage only.
/**
* @example
* ```typescript
* const cluster = createAuroraCluster(this, 'MyCluster', {
* vpc: myVpc,
* databaseName: 'production-db',
* });
* ```
*/
@see - Related References
Link to related types or functions.
/**
* @see {@link AuroraClusterProps} for configuration options
*/
@defaultValue - Default Values
Use inline for optional properties.
/** Instance type for the cluster. @defaultValue `r6g.large` */
instanceType?: InstanceType;
@deprecated - Deprecation Notice
Mark deprecated APIs with brief migration guidance.
/**
* @deprecated Use {@link createAuroraClusterV2} instead. Will be removed in v2.0.0.
*/
Common Patterns
Types
/**
* Configuration properties for Aurora PostgreSQL cluster.
*
* @example
* ```typescript
* const props: AuroraClusterProps = {
* vpc: myVpc,
* databaseName: 'production-db',
* };
* ```
*
* @public
*/
export type AuroraClusterProps = {
/** VPC where the cluster will be deployed. */
vpc: IVpc;
/** Name of the database to create. */
databaseName: string;
/** Instance type for the cluster. @defaultValue `r6g.large` */
instanceType?: InstanceType;
};
Functions
/**
* Creates an Aurora PostgreSQL cluster with production-ready configuration.
*
* @remarks
* Requires VPC with at least 2 private subnets in different AZs.
*
* @param scope - The CDK construct scope
* @param id - Unique identifier for this construct
* @param props - Configuration properties for the cluster
* @returns The created Aurora cluster instance
*
* @example
* ```typescript
* const cluster = createAuroraCluster(this, 'MyCluster', {
* vpc: myVpc,
* databaseName: 'production',
* });
* ```
*
* @see {@link AuroraClusterProps} for configuration options
* @public
*/
export const createAuroraCluster = (scope: Construct, id: string, props: AuroraClusterProps): DatabaseCluster => {
// Implementation
};
Enums
/**
* AWS Account ID enumeration for multi-account deployments.
*
* @example
* ```typescript
* const env = {
* account: Account.PROD,
* region: 'us-east-1',
* };
* ```
*
* @see {@link EnvironmentConfig} for environment configuration
* @public
*/
export enum Account {
/** Build account for CI/CD and artifact generation. */
BUILD = '000000000000',
/** Development account for active development and testing. */
DEV = '111111111111',
}
CDK Constructs (Classes)
/**
* Creates a CodeArtifact repository with domain configuration.
*
* @example
* ```typescript
* new CodeArtifactStack(this, 'CodeArtifact', {
* account: Account.BUILD,
* region: Region.US_EAST_1,
* name: Environment.BUILD,
* owner: 'platform-team',
* codeArtifactDomainName: 'my-domain',
* codeArtifactRepositoryName: 'my-repo',
* });
* ```
*
* @public
*/
export class CodeArtifactStack extends Stack {
/**
* Creates a new CodeArtifact stack.
*
* @param scope - The parent construct
* @param id - Unique identifier for this stack
* @param props - Stack properties including environment config
*/
constructor(scope: Construct, id: string, props: CodeArtifactStackPropsWithEnv) {
// Implementation
}
}
Anti-Patterns (What NOT to Do)
❌ Don't: Verbose property descriptions
export type Props = {
/**
* The name of the database.
*
* @remarks
* Must be 1-63 characters, alphanumeric and underscores only.
* Cannot start with a number. This follows AWS RDS naming conventions.
* The database will be created automatically during cluster provisioning.
*/
databaseName: string;
};
✅ Do: Concise one-liners
export type Props = {
/** Name of the database to create. */
databaseName: string;
};
❌ Don't: Multiple examples
/**
* @example
* Basic usage:
* ```typescript
* const cluster = create(...);
* ```
*
* @example
* Advanced usage:
* ```typescript
* const cluster = create(..., {advanced: true});
* ```
*/
✅ Do: One simple example
/**
* @example
* ```typescript
* const cluster = create(this, 'Cluster', {vpc: myVpc});
* ```
*/
❌ Don't: Explain implementation details
/**
* Loops through subnets and creates security groups using CDK's Subnet class
*/
✅ Do: Explain what it does
/**
* Configures database in private subnets for security.
*/
❌ Don't: Tutorial-style documentation
/**
* @remarks
* This construct provides the following features:
* 1. Automatic backups with 7-day retention
* 2. CloudWatch monitoring with custom alarms
* 3. Secrets Manager integration for credentials
* 4. Multi-AZ deployment for high availability
* 5. Encryption at rest using KMS
* 6. Enhanced monitoring with 60-second granularity
*
* To use this construct, first create a VPC...
*/
✅ Do: Brief critical information only
/**
* @remarks
* Requires VPC with at least 2 private subnets in different AZs.
*/
Documentation Checklist
Before committing, ensure:
- Every public function/type has a brief description
- All parameters documented with one-line
@param - Visibility tagged (
@public,@internal,@private) - Type properties use one-line
/** */format - Functions have one simple
@examplemaximum -
@remarksonly for critical prerequisites/warnings - Types linked with
{@link TypeName}where relevant - No verbose explanations (save for
/docs)
Tools Integration
TSDoc comments integrate with:
- VS Code IntelliSense - Hover tooltips (primary use case)
- TypeDoc - Generated documentation sites
- API Extractor - API documentation reports
Comprehensive guides belong in /docs directories within each subpackage.