chore(toolkit): generate docs (#32991)

In lack of a public docs page, use typedoc for now.

### Description of how you validated changes

Docs only

### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

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

Author: mrgrain

packages/@aws-cdk/toolkit/.npmignore

@@ -9,6 +9,7 @@ dist
 coverage
 .nyc_output
 *.tgz
+docs
 
 # Ignore config files
 .eslintrc.js

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

@@ -34,7 +34,7 @@ export class DiffMethod {
    *
    * This will create, analyze, and subsequently delete a changeset against the CloudFormation stack.
    */
-  public static ChangeSet(options: ChangeSetDiffOptions = {}) {
+  public static ChangeSet(options: ChangeSetDiffOptions = {}): DiffMethod {
     return new class extends DiffMethod {
       public override readonly options: ChangeSetDiffOptions;
       public constructor(opts: ChangeSetDiffOptions) {
@@ -44,7 +44,7 @@ export class DiffMethod {
     }(options);
   }
 
-  public static TemplateOnly(options: CloudFormationDiffOptions = {}) {
+  public static TemplateOnly(options: CloudFormationDiffOptions = {}): DiffMethod {
     return new class extends DiffMethod {
       public override readonly options: CloudFormationDiffOptions;
       public constructor(opts: CloudFormationDiffOptions) {
@@ -54,7 +54,7 @@ export class DiffMethod {
     }(options);
   }
 
-  public static LocalFile(path: string) {
+  public static LocalFile(path: string): DiffMethod {
     return new class extends DiffMethod {
       public override readonly options: { path: string };
       public constructor(opts: { path: string }) {

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

@@ -19,6 +19,9 @@ export abstract class CloudAssemblySourceBuilder {
 
   /**
    * Create a Cloud Assembly from a Cloud Assembly builder function.
+   * @param builder the builder function
+   * @param props additional configuration properties
+   * @returns the CloudAssembly source
    */
   public async fromAssemblyBuilder(
     builder: AssemblyBuilder,
@@ -52,9 +55,8 @@ export abstract class CloudAssemblySourceBuilder {
 
   /**
    * Creates a Cloud Assembly from an existing assembly directory.
-   * @param directory the directory of the AWS CDK app. Defaults to the current working directory.
-   * @param props additional configuration properties
-   * @returns an instance of `AwsCdkCli`
+   * @param directory the directory of a already produced Cloud Assembly.
+   * @returns the CloudAssembly source
    */
   public async fromAssemblyDirectory(directory: string): Promise<ICloudAssemblySource> {
     const services: ToolkitServices = await this.toolkitServices();
@@ -78,9 +80,8 @@ export abstract class CloudAssemblySourceBuilder {
   }
   /**
    * Use a directory containing an AWS CDK app as source.
-   * @param directory the directory of the AWS CDK app. Defaults to the current working directory.
    * @param props additional configuration properties
-   * @returns an instance of `AwsCdkCli`
+   * @returns the CloudAssembly source
    */
   public async fromCdkApp(app: string, props: CdkAppSourceProps = {}): Promise<ICloudAssemblySource> {
     const services: ToolkitServices = await this.toolkitServices();

packages/@aws-cdk/toolkit/lib/api/cloud-assembly/stack-assembly.ts

@@ -87,7 +87,6 @@ export class StackAssembly extends CloudAssembly implements ICloudAssemblySource
   /**
    * Select all stacks that have the validateOnSynth flag et.
    *
-   * @param assembly
    * @returns a `StackCollection` of all stacks that needs to be validated
    */
   public selectStacksForValidation() {

packages/@aws-cdk/toolkit/package.json

@@ -20,6 +20,7 @@
     "build+extract": "yarn build",
     "build+test+extract": "yarn build+test",
     "bundle": "node bundle.mjs",
+    "docs": "typedoc lib/index.ts --excludeExternals --excludePrivate --excludeProtected --excludeInternal",
     "lint": "cdk-lint",
     "package": "cdk-package",
     "pkglint": "pkglint -f",
@@ -49,6 +50,7 @@
     "aws-cdk-lib": "0.0.0",
     "esbuild": "^0.24.0",
     "jest": "^29.7.0",
+    "typedoc": "^0.27.6",
     "typescript": "~5.6.3"
   },
   "dependencies": {