Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
67477f0
Initial plan
Copilot Nov 13, 2025
0ea3768
Add @module comment support to namespace declarations
Copilot Nov 13, 2025
6194749
Add validation for multiple @module tags
Copilot Nov 17, 2025
7abbfa5
Add changelog entry and remove unused import
Copilot Nov 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions apps/api-extractor/extends/tsdoc-base.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
Copy link

@octogonz-dev octogonz-dev Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since @module is already defined by JSDoc, we should probably make it a standard TSDoc tag rather than an AEDoc custom tag. If the JSDoc syntax is inconsistent or has different semantics, then maybe TSDoc should consider a different name like @moduleDocumentation.

"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand All @@ -51,6 +55,7 @@
"@internal": true,
"@label": true,
"@link": true,
"@module": true,
"@override": true,
"@packageDocumentation": true,
"@param": true,
Expand Down
37 changes: 37 additions & 0 deletions apps/api-extractor/src/aedoc/ModuleDocComment.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.

import * as ts from 'typescript';

export class ModuleDocComment {
Copy link

@octogonz-dev octogonz-dev Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

DRY - this is essentially a copy+paste of the code+comments from PackageDocComment.ts, introducing a second full scan of the AST. And it does not conider a comment block containing both @module and @packageDocumentation, which probably should be an error. I feel like probably these tags should be detected in a single unified scan. But we need to generalize it a bit, because the @packageDocumentation code assumed that it can only appear in the entry point file, whereas @module can appear in any file.

/**
* For the given source file, see if it starts with a TSDoc comment containing the `@module` tag.
*/
public static tryFindInSourceFile(sourceFile: ts.SourceFile): ts.TextRange | undefined {
// The @module comment is special because it is not attached to an AST
// definition. Instead, it is part of the "trivia" tokens that the compiler treats
// as irrelevant white space.
//
// This implementation assumes that the "@module" will be in the first TSDoc comment
// that appears in the source file.
let moduleCommentRange: ts.TextRange | undefined = undefined;

for (const commentRange of ts.getLeadingCommentRanges(sourceFile.text, sourceFile.getFullStart()) || []) {
if (commentRange.kind === ts.SyntaxKind.MultiLineCommentTrivia) {
const commentBody: string = sourceFile.text.substring(commentRange.pos, commentRange.end);

// Choose the first JSDoc-style comment
if (/^\s*\/\*\*/.test(commentBody)) {
// But only if it looks like it's trying to be @module
// (The TSDoc parser will validate this more rigorously)
if (/\@module/i.test(commentBody)) {
moduleCommentRange = commentRange;
}
break;
}
}
}

return moduleCommentRange;
}
}
19 changes: 19 additions & 0 deletions apps/api-extractor/src/generators/DtsRollupGenerator.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ import { AstNamespaceImport } from '../analyzer/AstNamespaceImport';
import type { IAstModuleExportInfo } from '../analyzer/AstModule';
import { SourceFileLocationFormatter } from '../analyzer/SourceFileLocationFormatter';
import type { AstEntity } from '../analyzer/AstEntity';
import { ModuleDocComment } from '../aedoc/ModuleDocComment';

/**
* Used with DtsRollupGenerator.writeTypingsFile()
Expand Down Expand Up @@ -180,6 +181,18 @@ export class DtsRollupGenerator {
// signatures may reference them directly (without using the namespace qualifier).

writer.ensureSkippedLine();

// Check if the source file has a @module comment and emit it before the namespace declaration
const sourceFile: ts.SourceFile = astEntity.astModule.sourceFile;
const moduleCommentRange: ts.TextRange | undefined = ModuleDocComment.tryFindInSourceFile(sourceFile);
if (moduleCommentRange) {
const moduleComment: string = sourceFile.text.substring(
moduleCommentRange.pos,
moduleCommentRange.end
);
writer.writeLine(moduleComment);
}

if (entity.shouldInlineExport) {
writer.write('export ');
}
Expand Down Expand Up @@ -265,6 +278,12 @@ export class DtsRollupGenerator {
span.modification.skipAll();
}

// If the @module comment seems to be attached to one of the regular API items,
// omit it. It gets emitted with the namespace declaration.
if (span.node.getText().match(/(?:\s|\*)@module(?:\s|\*)/gi)) {
span.modification.skipAll();
}
Comment on lines +284 to +288
Copy link
Member

@iclanton iclanton Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot - This should be an error case, shouldn't it? The @module comment should only be valid for a module re-exported as a namespace, right?

Copy link
Contributor Author

Copilot AI Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Currently, @module comments on regular API items are silently skipped (similar to how @packageDocumentation is handled). The @module comment from the source file is only used when that module is re-exported as a namespace.

Should we report an error if a file contains @module but is NOT re-exported as a namespace? Or is silent skipping the right behavior? I'd like clarification on the intended validation rules.


// For now, we don't transform JSDoc comment nodes at all
recurseChildren = false;
break;
Expand Down
5 changes: 5 additions & 0 deletions build-tests/api-extractor-scenarios/etc/ambientNameConflict/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand Down Expand Up @@ -171,6 +175,7 @@
"@virtual": true,
"@betaDocumentation": true,
"@internalRemarks": true,
"@module": true,
"@preapproved": true
},
"reportUnsupportedHtmlElements": false
Expand Down
5 changes: 5 additions & 0 deletions ...d-tests/api-extractor-scenarios/etc/ambientNameConflict2/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand Down Expand Up @@ -171,6 +175,7 @@
"@virtual": true,
"@betaDocumentation": true,
"@internalRemarks": true,
"@module": true,
"@preapproved": true
},
"reportUnsupportedHtmlElements": false
Expand Down
5 changes: 5 additions & 0 deletions ...-tests/api-extractor-scenarios/etc/ancillaryDeclarations/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand Down Expand Up @@ -171,6 +175,7 @@
"@virtual": true,
"@betaDocumentation": true,
"@internalRemarks": true,
"@module": true,
"@preapproved": true
},
"reportUnsupportedHtmlElements": false
Expand Down
5 changes: 5 additions & 0 deletions build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand Down Expand Up @@ -171,6 +175,7 @@
"@virtual": true,
"@betaDocumentation": true,
"@internalRemarks": true,
"@module": true,
"@preapproved": true
},
"reportUnsupportedHtmlElements": false
Expand Down
5 changes: 5 additions & 0 deletions build-tests/api-extractor-scenarios/etc/bundledPackages/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand Down Expand Up @@ -171,6 +175,7 @@
"@virtual": true,
"@betaDocumentation": true,
"@internalRemarks": true,
"@module": true,
"@preapproved": true
},
"reportUnsupportedHtmlElements": false
Expand Down
5 changes: 5 additions & 0 deletions ...ests/api-extractor-scenarios/etc/bundlerModuleResolution/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand Down Expand Up @@ -171,6 +175,7 @@
"@virtual": true,
"@betaDocumentation": true,
"@internalRemarks": true,
"@module": true,
"@preapproved": true
},
"reportUnsupportedHtmlElements": false
Expand Down
5 changes: 5 additions & 0 deletions build-tests/api-extractor-scenarios/etc/circularImport/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand Down Expand Up @@ -171,6 +175,7 @@
"@virtual": true,
"@betaDocumentation": true,
"@internalRemarks": true,
"@module": true,
"@preapproved": true
},
"reportUnsupportedHtmlElements": false
Expand Down
5 changes: 5 additions & 0 deletions build-tests/api-extractor-scenarios/etc/circularImport2/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand Down Expand Up @@ -171,6 +175,7 @@
"@virtual": true,
"@betaDocumentation": true,
"@internalRemarks": true,
"@module": true,
"@preapproved": true
},
"reportUnsupportedHtmlElements": false
Expand Down
5 changes: 5 additions & 0 deletions ...ts/api-extractor-scenarios/etc/defaultExportOfEntryPoint/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand Down Expand Up @@ -171,6 +175,7 @@
"@virtual": true,
"@betaDocumentation": true,
"@internalRemarks": true,
"@module": true,
"@preapproved": true
},
"reportUnsupportedHtmlElements": false
Expand Down
5 changes: 5 additions & 0 deletions ...s/api-extractor-scenarios/etc/defaultExportOfEntryPoint2/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand Down Expand Up @@ -171,6 +175,7 @@
"@virtual": true,
"@betaDocumentation": true,
"@internalRemarks": true,
"@module": true,
"@preapproved": true
},
"reportUnsupportedHtmlElements": false
Expand Down
5 changes: 5 additions & 0 deletions ...s/api-extractor-scenarios/etc/defaultExportOfEntryPoint3/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand Down Expand Up @@ -171,6 +175,7 @@
"@virtual": true,
"@betaDocumentation": true,
"@internalRemarks": true,
"@module": true,
"@preapproved": true
},
"reportUnsupportedHtmlElements": false
Expand Down
5 changes: 5 additions & 0 deletions ...s/api-extractor-scenarios/etc/defaultExportOfEntryPoint4/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand Down Expand Up @@ -171,6 +175,7 @@
"@virtual": true,
"@betaDocumentation": true,
"@internalRemarks": true,
"@module": true,
"@preapproved": true
},
"reportUnsupportedHtmlElements": false
Expand Down
5 changes: 5 additions & 0 deletions build-tests/api-extractor-scenarios/etc/docReferences/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand Down Expand Up @@ -171,6 +175,7 @@
"@virtual": true,
"@betaDocumentation": true,
"@internalRemarks": true,
"@module": true,
"@preapproved": true
},
"reportUnsupportedHtmlElements": false
Expand Down
5 changes: 5 additions & 0 deletions build-tests/api-extractor-scenarios/etc/docReferences2/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand Down Expand Up @@ -171,6 +175,7 @@
"@virtual": true,
"@betaDocumentation": true,
"@internalRemarks": true,
"@module": true,
"@preapproved": true
},
"reportUnsupportedHtmlElements": false
Expand Down
5 changes: 5 additions & 0 deletions build-tests/api-extractor-scenarios/etc/docReferences3/api-extractor-scenarios.api.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@
"tagName": "@internalRemarks",
"syntaxKind": "block"
},
{
"tagName": "@module",
"syntaxKind": "modifier"
},
{
"tagName": "@preapproved",
"syntaxKind": "modifier"
Expand Down Expand Up @@ -171,6 +175,7 @@
"@virtual": true,
"@betaDocumentation": true,
"@internalRemarks": true,
"@module": true,
"@preapproved": true
},
"reportUnsupportedHtmlElements": false
Expand Down
Loading
Loading