chore(toolkit-lib): resolve API Extractor warnings and improve documentation (#489)

This PR addresses API Extractor warnings in the toolkit-lib package:

- Updates API Extractor configuration to treat most issues as errors
- Configures proper handling of specific warnings like 
- Adds support for `@module` tag in TSDoc configuration
- Fixes documentation formatting issues in source files to comply with
API Extractor requirements
- Makes parameter descriptions consistent with hyphen format

These changes help maintain better API documentation quality and reduce
warning noise during builds.

---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

Author: mrgrain

.projenrc.ts

@@ -860,20 +860,23 @@ new pj.JsonFile(toolkitLib, 'api-extractor.json', {
     messages: {
       compilerMessageReporting: {
         default: {
-          logLevel: 'warning',
+          logLevel: 'error',
         },
       },
       extractorMessageReporting: {
         'default': {
-          logLevel: 'warning',
+          logLevel: 'error',
         },
         'ae-missing-release-tag': {
           logLevel: 'none',
         },
+        'ae-forgotten-export': {
+          logLevel: 'warning', // @todo fix issues and change to error
+        },
       },
       tsdocMessageReporting: {
         default: {
-          logLevel: 'warning',
+          logLevel: 'error',
         },
       },
     },
@@ -894,9 +897,14 @@ new pj.JsonFile(toolkitLib, 'tsdoc.json', {
         tagName: '@default',
         syntaxKind: 'block',
       },
+      {
+        tagName: '@module',
+        syntaxKind: 'block',
+      },
     ],
     supportForTags: {
       '@default': true,
+      '@module': true,
     },
   },
 });

packages/@aws-cdk/toolkit-lib/api-extractor.json

@@ -23,7 +23,7 @@ export interface ChangeSetDiffOptions extends CloudFormationDiffOptions {
   /**
    * Additional parameters for CloudFormation when creating a diff change set
    *
-   * @default {}
+   * @default - no parameters
    */
   readonly parameters?: { [name: string]: string | undefined };
 }

packages/@aws-cdk/toolkit-lib/lib/actions/diff/index.ts

@@ -37,8 +37,8 @@ export abstract class CloudAssemblySourceBuilder {
    * directory. This means that while the CloudAssembly is being used, no CDK
    * app synthesis can take place into that directory.
    *
-   * @param builder the builder function
-   * @param props additional configuration properties
+   * @param builder - the builder function
+   * @param props - additional configuration properties
    * @returns the CloudAssembly source
    */
   public async fromAssemblyBuilder(
@@ -102,7 +102,7 @@ export abstract class CloudAssemblySourceBuilder {
    * the CloudAssembly is being used, no CDK app synthesis can take place into
    * that directory.
    *
-   * @param directory the directory of a already produced Cloud Assembly.
+   * @param directory - directory the directory of a already produced Cloud Assembly.
    * @returns the CloudAssembly source
    */
   public async fromAssemblyDirectory(directory: string, props: AssemblyDirectoryProps = {}): Promise<ICloudAssemblySource> {
@@ -146,7 +146,7 @@ export abstract class CloudAssemblySourceBuilder {
    * directory.  This means that while the CloudAssembly is being used, no CDK
    * app synthesis can take place into that directory.
    *
-   * @param props additional configuration properties
+   * @param props - additional configuration properties
    * @returns the CloudAssembly source
    */
   public async fromCdkApp(app: string, props: FromCdkAppOptions = {}): Promise<ICloudAssemblySource> {

packages/@aws-cdk/toolkit-lib/lib/api/cloud-assembly/private/source-builder.ts

@@ -30,10 +30,10 @@ export class PluginHost implements IPluginHost {
    *
    * Will use `require.resolve()` to get the most accurate representation of what
    * code will get loaded in error messages. As such, it will not work in
-   * unit tests with Jest virtual modules becauase of <https://github.com/jestjs/jest/issues/9543>.
+   * unit tests with Jest virtual modules becauase of \<https://github.com/jestjs/jest/issues/9543\>.
    *
-   * @param moduleSpec the specification (path or name) of the plug-in module to be loaded.
-   * @param ioHost the I/O host to use for printing progress information
+   * @param moduleSpec - the specification (path or name) of the plug-in module to be loaded.
+   * @param ioHost - the I/O host to use for printing progress information
    */
   public load(moduleSpec: string, ioHost?: IIoHost) {
     try {
@@ -85,7 +85,7 @@ export class PluginHost implements IPluginHost {
   /**
    * Allows plug-ins to register new CredentialProviderSources.
    *
-   * @param source a new CredentialProviderSource to register.
+   * @param source - a new CredentialProviderSource to register.
    */
   public registerCredentialProviderSource(source: CredentialProviderSource) {
     // Forward to the right credentials-related plugin host