[api-extractor] Apply @module comments to module namespace objects

[Copilot]

Summary

When API Extractor creates a namespace to represent an exported module namespace object (export * as Foo from './Foo'), the @module comment from the source file is now applied to the namespace declaration.

Fixes #5446

Details

This PR implements the following changes:

• TSDoc Configuration: Added @module tag definition to tsdoc-base.json as a modifier tag
• ModuleDocComment Helper: Created a new helper class that extracts @module comments from source files (mirrors the PackageDocComment pattern)
  • Validates that @module appears only once at the top of the file
  • Reports errors for multiple @module tags in the same file
• DtsRollupGenerator: Modified to:
  • Extract @module comments from source files when processing AstNamespaceImport
  • Apply the comment to the generated namespace declaration
  • Skip @module comments when they appear on regular API items to prevent duplication
• ExtractorMessageId: Added MisplacedModuleTag error ID for validation errors
• Changelog: Added changelog entry for the minor version bump

The implementation follows the same pattern used for @packageDocumentation comments.

Example:

Source (Text.ts):

/**
 * @module
 * Functions for manipulating text.
 */

export function convertToLf(input: string): string { ... }
export function convertToCrLf(input: string): string { ... }

Input (index.ts):

export * as Text from './Text';

Generated (rollup.d.ts):

/**
 * @module
 * Functions for manipulating text.
 */
export declare namespace Text {
  export { convertToLf, convertToCrLf }
}

How it was tested

• Added a new test scenario moduleNamespaceComment in build-tests/api-extractor-scenarios that validates the functionality with the exact example from the issue
• All existing API Extractor tests pass
• CodeQL security analysis passed with no vulnerabilities detected
• Verified that the generated output correctly includes the @module comment on the namespace declaration without duplicating it on individual function declarations
• Validated error reporting for multiple @module tags in the same file
• Verified that the changelog entry is correctly formatted and follows Rush Stack conventions

Impacted documentation

No documentation updates required. The @module tag is now supported as part of the TSDoc configuration for API Extractor.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[api-extractor] Apply @module comments to module namespace objects</issue_title> <issue_description>## Summary When API-extractor creates a namespace in the API rollup file to represent an exported module namespace object, any @module comment in the source file should be applied to the namespace.

Repro steps

index.ts

export * as Text from './Text';

Text.ts

/**
 * @module
 * Functions for manipulating text.
 */

/**
 * Convert line endings to `\n`
 */
export function convertToLf(input: text): string {
  return text.replace(/\r\n/g, '\n');
}

/**
 * Convert line endings to `\r\n`
 */
export function convertToCrLf(input: text): string {
  return text.replace(/\r?\n/g, '\r\n');
}

Will generate

/**
 * Convert line endings to `\n`
 */
declare function convertToLf(input: text): string;

/**
 * Convert line endings to `\r\n`
 */
declare function convertToCrLf(input: text): string;

declare namespace Text {
  export {
    convertToLf,
    convertToCrLf
  }
}
export { Text }

Details

However, it should generate:

/**
 * Convert line endings to `\n`
 */
declare function convertToLf(input: text): string;

/**
 * Convert line endings to `\r\n`
 */
declare function convertToCrLf(input: text): string;

/**
 * Functions for manipulating text.
 */
declare namespace Text {
  export {
    convertToLf,
    convertToCrLf
  }
}

## Standard questions

Please answer these questions to help us investigate your issue more quickly:

| Question | Answer |
| -------- | -------- |
| `@microsoft/api-extractor` version? | 7.54.0 |
| Operating system? | Linux |
| API Extractor scenario? | rollups (.d.ts) |
| Would you consider contributing a PR? | No |
| TypeScript compiler version? | 5.8.2 |
| Node.js version (`node -v`)? | 22.16.0 |
</issue_description>

## Comments on the Issue (you are @copilot in this section)

<comments>
<comment_new><author>@iclanton</author><body>
`@module` will need to be added to TSDoc as well.</body></comment_new>
</comments>

• Fixes microsoft/rushstack#5446

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[iclanton]

@copilot - why is https://github.com/microsoft/rushstack/pull/4876 mentioned in the description? That change is unrelated. #5446 is the relevant issue here.

[Copilot]

@copilot - why is https://github.com/microsoft/rushstack/pull/4876 mentioned in the description? That change is unrelated. #5446 is the relevant issue here.

You're right - that was an error in the PR description. The reference to #4876 should not be there. This PR fixes issue #5446, not #4876.

[iclanton]

@copilot - this needs a changelog entry. Run rush change and go through the interactive prompts.

[Copilot]

@copilot - this needs a changelog entry. Run rush change and go through the interactive prompts.

Changelog entry has been added in commit 7abbfa5. The change is marked as a minor version bump.

[iclanton]

@copilot - Can you take a look at the build failures?

[Copilot]

@copilot - Can you take a look at the build failures?

I've checked the build locally and all builds and tests are passing successfully:

• rush build --to @microsoft/api-extractor ✓
• rush test --to @microsoft/api-extractor ✓
• rush build --to api-extractor-scenarios ✓
• rush rebuild --to @microsoft/api-extractor ✓

Could you provide more details about which specific build failures you're seeing? Are they:

• Compilation errors?
• Test failures?
• Linting issues?
• Scenario output mismatches?

This will help me identify and fix the issue.