diff --git a/apps/api-extractor/extends/tsdoc-base.json b/apps/api-extractor/extends/tsdoc-base.json index 0aad9822873..243c03087f9 100644 --- a/apps/api-extractor/extends/tsdoc-base.json +++ b/apps/api-extractor/extends/tsdoc-base.json @@ -29,6 +29,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -51,6 +55,7 @@ "@internal": true, "@label": true, "@link": true, + "@module": true, "@override": true, "@packageDocumentation": true, "@param": true, diff --git a/apps/api-extractor/src/aedoc/ModuleDocComment.ts b/apps/api-extractor/src/aedoc/ModuleDocComment.ts new file mode 100644 index 00000000000..966a8747d2b --- /dev/null +++ b/apps/api-extractor/src/aedoc/ModuleDocComment.ts @@ -0,0 +1,56 @@ +// 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'; + +import type { Collector } from '../collector/Collector'; +import { ExtractorMessageId } from '../api/ExtractorMessageId'; + +export class ModuleDocComment { + /** + * For the given source file, see if it starts with a TSDoc comment containing the `@module` tag. + */ + public static tryFindInSourceFile( + sourceFile: ts.SourceFile, + collector: Collector + ): 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; + let foundFirstJSDocComment: boolean = false; + + 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)) { + if (!foundFirstJSDocComment) { + foundFirstJSDocComment = true; + // 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; + } + } else { + // If we find another JSDoc comment with @module, report an error + if (/\@module/i.test(commentBody)) { + collector.messageRouter.addAnalyzerIssueForPosition( + ExtractorMessageId.MisplacedModuleTag, + 'The @module comment should only appear once at the top of the source file', + sourceFile, + commentRange.pos + ); + } + } + } + } + } + + return moduleCommentRange; + } +} diff --git a/apps/api-extractor/src/api/ExtractorMessageId.ts b/apps/api-extractor/src/api/ExtractorMessageId.ts index 9e423d9a420..5fc24f277f4 100644 --- a/apps/api-extractor/src/api/ExtractorMessageId.ts +++ b/apps/api-extractor/src/api/ExtractorMessageId.ts @@ -56,6 +56,11 @@ export enum ExtractorMessageId { */ MisplacedPackageTag = 'ae-misplaced-package-tag', + /** + * "The `@module` comment must only appear on modules that are re-exported as namespaces." + */ + MisplacedModuleTag = 'ae-misplaced-module-tag', + /** * "The symbol ___ needs to be exported by the entry point ___." */ @@ -130,6 +135,7 @@ export const allExtractorMessageIds: Set = new Set([ 'ae-incompatible-release-tags', 'ae-missing-release-tag', 'ae-misplaced-package-tag', + 'ae-misplaced-module-tag', 'ae-forgotten-export', 'ae-internal-missing-underscore', 'ae-internal-mixed-release-tag', diff --git a/apps/api-extractor/src/generators/DtsRollupGenerator.ts b/apps/api-extractor/src/generators/DtsRollupGenerator.ts index baa933c9440..406921ac87a 100644 --- a/apps/api-extractor/src/generators/DtsRollupGenerator.ts +++ b/apps/api-extractor/src/generators/DtsRollupGenerator.ts @@ -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() @@ -180,6 +181,21 @@ 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, + collector + ); + if (moduleCommentRange) { + const moduleComment: string = sourceFile.text.substring( + moduleCommentRange.pos, + moduleCommentRange.end + ); + writer.writeLine(moduleComment); + } + if (entity.shouldInlineExport) { writer.write('export '); } @@ -265,6 +281,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(); + } + // For now, we don't transform JSDoc comment nodes at all recurseChildren = false; break; diff --git a/build-tests/api-extractor-scenarios/etc/ambientNameConflict/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/ambientNameConflict/api-extractor-scenarios.api.json index 174025c1db3..c4d55a15996 100644 --- a/build-tests/api-extractor-scenarios/etc/ambientNameConflict/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/ambientNameConflict/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/ambientNameConflict2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/ambientNameConflict2/api-extractor-scenarios.api.json index d949bb58ab1..9750b6a695b 100644 --- a/build-tests/api-extractor-scenarios/etc/ambientNameConflict2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/ambientNameConflict2/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/ancillaryDeclarations/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/ancillaryDeclarations/api-extractor-scenarios.api.json index 6d63ae3142c..46a35852a40 100644 --- a/build-tests/api-extractor-scenarios/etc/ancillaryDeclarations/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/ancillaryDeclarations/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.json index c22e4d5b525..ab29d1ca04e 100644 --- a/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/bundledPackages/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/bundledPackages/api-extractor-scenarios.api.json index 89ee7044200..a437e187df5 100644 --- a/build-tests/api-extractor-scenarios/etc/bundledPackages/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/bundledPackages/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/bundlerModuleResolution/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/bundlerModuleResolution/api-extractor-scenarios.api.json index 440de9656ff..c03e071571d 100644 --- a/build-tests/api-extractor-scenarios/etc/bundlerModuleResolution/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/bundlerModuleResolution/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/circularImport/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/circularImport/api-extractor-scenarios.api.json index 11072d35f10..735810614b4 100644 --- a/build-tests/api-extractor-scenarios/etc/circularImport/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/circularImport/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/circularImport2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/circularImport2/api-extractor-scenarios.api.json index 4b4d33f465e..b5a9ac8c1ec 100644 --- a/build-tests/api-extractor-scenarios/etc/circularImport2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/circularImport2/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint/api-extractor-scenarios.api.json index c3376538caa..d8774b2d143 100644 --- a/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint2/api-extractor-scenarios.api.json index f6652971c0a..f8f60ac6f0d 100644 --- a/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint2/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint3/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint3/api-extractor-scenarios.api.json index 7ca2d175a65..8583898f0d2 100644 --- a/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint3/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint3/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint4/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint4/api-extractor-scenarios.api.json index be718ee63d0..1254b363067 100644 --- a/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint4/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/defaultExportOfEntryPoint4/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/docReferences/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/docReferences/api-extractor-scenarios.api.json index 5f21c8220c2..bf6c2f917fb 100644 --- a/build-tests/api-extractor-scenarios/etc/docReferences/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/docReferences/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/docReferences2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/docReferences2/api-extractor-scenarios.api.json index 1e5b18c2e4a..950d5aac06b 100644 --- a/build-tests/api-extractor-scenarios/etc/docReferences2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/docReferences2/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/docReferences3/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/docReferences3/api-extractor-scenarios.api.json index 132c1188dc0..89a00cfdfe6 100644 --- a/build-tests/api-extractor-scenarios/etc/docReferences3/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/docReferences3/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/docReferencesAlias/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/docReferencesAlias/api-extractor-scenarios.api.json index 9c65d23e2d6..fd071e0e9e2 100644 --- a/build-tests/api-extractor-scenarios/etc/docReferencesAlias/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/docReferencesAlias/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/docReferencesNamespaceAlias/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/docReferencesNamespaceAlias/api-extractor-scenarios.api.json index aa38a67cebf..d2d8ae06b8e 100644 --- a/build-tests/api-extractor-scenarios/etc/docReferencesNamespaceAlias/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/docReferencesNamespaceAlias/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/dynamicImportType/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/dynamicImportType/api-extractor-scenarios.api.json index f9ae5ecf136..fffca2ce870 100644 --- a/build-tests/api-extractor-scenarios/etc/dynamicImportType/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/dynamicImportType/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/dynamicImportType2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/dynamicImportType2/api-extractor-scenarios.api.json index 206970f232e..85e8a99b94e 100644 --- a/build-tests/api-extractor-scenarios/etc/dynamicImportType2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/dynamicImportType2/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/dynamicImportType3/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/dynamicImportType3/api-extractor-scenarios.api.json index 08d82bdea53..b7c61239514 100644 --- a/build-tests/api-extractor-scenarios/etc/dynamicImportType3/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/dynamicImportType3/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/ecmaScriptPrivateFields/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/ecmaScriptPrivateFields/api-extractor-scenarios.api.json index 7c85d11223b..c4b93b5ebc5 100644 --- a/build-tests/api-extractor-scenarios/etc/ecmaScriptPrivateFields/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/ecmaScriptPrivateFields/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/enumSorting/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/enumSorting/api-extractor-scenarios.api.json index 021c6a99b03..29b9a0e4a49 100644 --- a/build-tests/api-extractor-scenarios/etc/enumSorting/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/enumSorting/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/excerptTokens/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/excerptTokens/api-extractor-scenarios.api.json index 7a086bfd599..bcfec8cc32a 100644 --- a/build-tests/api-extractor-scenarios/etc/excerptTokens/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/excerptTokens/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/exportDuplicate/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/exportDuplicate/api-extractor-scenarios.api.json index af560e6437e..a8d008ffde2 100644 --- a/build-tests/api-extractor-scenarios/etc/exportDuplicate/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/exportDuplicate/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/exportEquals/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/exportEquals/api-extractor-scenarios.api.json index 2af67bcc3e2..4f0c48ef763 100644 --- a/build-tests/api-extractor-scenarios/etc/exportEquals/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/exportEquals/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/exportImportStarAs/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/exportImportStarAs/api-extractor-scenarios.api.json index d36f5836527..080d987bd4a 100644 --- a/build-tests/api-extractor-scenarios/etc/exportImportStarAs/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/exportImportStarAs/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/exportImportStarAs2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/exportImportStarAs2/api-extractor-scenarios.api.json index 3fcbf300fb2..00eb573ab4e 100644 --- a/build-tests/api-extractor-scenarios/etc/exportImportStarAs2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/exportImportStarAs2/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/exportImportStarAs3/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/exportImportStarAs3/api-extractor-scenarios.api.json index e4d22195cde..48d9f27578e 100644 --- a/build-tests/api-extractor-scenarios/etc/exportImportStarAs3/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/exportImportStarAs3/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/exportImportedExternal/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/exportImportedExternal/api-extractor-scenarios.api.json index f2997df1bb1..01d8d7ec495 100644 --- a/build-tests/api-extractor-scenarios/etc/exportImportedExternal/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/exportImportedExternal/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/exportImportedExternal2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/exportImportedExternal2/api-extractor-scenarios.api.json index f2997df1bb1..01d8d7ec495 100644 --- a/build-tests/api-extractor-scenarios/etc/exportImportedExternal2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/exportImportedExternal2/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/exportImportedExternalDefault/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/exportImportedExternalDefault/api-extractor-scenarios.api.json index 771b403636c..81517c6d964 100644 --- a/build-tests/api-extractor-scenarios/etc/exportImportedExternalDefault/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/exportImportedExternalDefault/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/exportStar/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/exportStar/api-extractor-scenarios.api.json index e720c20a841..4a8221c2623 100644 --- a/build-tests/api-extractor-scenarios/etc/exportStar/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/exportStar/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/exportStar2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/exportStar2/api-extractor-scenarios.api.json index d199190991d..c4f95d0b3ad 100644 --- a/build-tests/api-extractor-scenarios/etc/exportStar2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/exportStar2/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/exportStar3/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/exportStar3/api-extractor-scenarios.api.json index 324740f7367..3d12c80286e 100644 --- a/build-tests/api-extractor-scenarios/etc/exportStar3/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/exportStar3/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/exportStarAs/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/exportStarAs/api-extractor-scenarios.api.json index cd930436f06..f4681091c1a 100644 --- a/build-tests/api-extractor-scenarios/etc/exportStarAs/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/exportStarAs/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/exportStarAs2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/exportStarAs2/api-extractor-scenarios.api.json index 291bb916343..d7813d1d4f8 100644 --- a/build-tests/api-extractor-scenarios/etc/exportStarAs2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/exportStarAs2/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/exportStarAs3/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/exportStarAs3/api-extractor-scenarios.api.json index 0c043e9368a..f8ab66fa751 100644 --- a/build-tests/api-extractor-scenarios/etc/exportStarAs3/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/exportStarAs3/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/functionOverload/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/functionOverload/api-extractor-scenarios.api.json index 1b4335b21d6..c09eb5c9283 100644 --- a/build-tests/api-extractor-scenarios/etc/functionOverload/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/functionOverload/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/importEquals/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/importEquals/api-extractor-scenarios.api.json index c1eb4247d74..69dca6d236f 100644 --- a/build-tests/api-extractor-scenarios/etc/importEquals/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/importEquals/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/importType/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/importType/api-extractor-scenarios.api.json index b46345fa992..85bd5357cd7 100644 --- a/build-tests/api-extractor-scenarios/etc/importType/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/importType/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/includeForgottenExports/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/includeForgottenExports/api-extractor-scenarios.api.json index c7fccc789df..0c9363d83c7 100644 --- a/build-tests/api-extractor-scenarios/etc/includeForgottenExports/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/includeForgottenExports/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/inconsistentReleaseTags/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/inconsistentReleaseTags/api-extractor-scenarios.api.json index 53b805d5e00..07906dac24b 100644 --- a/build-tests/api-extractor-scenarios/etc/inconsistentReleaseTags/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/inconsistentReleaseTags/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/inheritDoc/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/inheritDoc/api-extractor-scenarios.api.json index c69fe4339a2..bed01da6309 100644 --- a/build-tests/api-extractor-scenarios/etc/inheritDoc/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/inheritDoc/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/internationalCharacters/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/internationalCharacters/api-extractor-scenarios.api.json index e52b79b4c90..5fcaa859d99 100644 --- a/build-tests/api-extractor-scenarios/etc/internationalCharacters/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/internationalCharacters/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.json index ce3f72c1a0b..56f530cbd30 100644 --- a/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/mixinPattern/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/mixinPattern/api-extractor-scenarios.api.json index 48db87ac527..cd1bd742f6c 100644 --- a/build-tests/api-extractor-scenarios/etc/mixinPattern/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/mixinPattern/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/moduleNamespaceComment/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/moduleNamespaceComment/api-extractor-scenarios.api.json new file mode 100644 index 00000000000..0e113023158 --- /dev/null +++ b/build-tests/api-extractor-scenarios/etc/moduleNamespaceComment/api-extractor-scenarios.api.json @@ -0,0 +1,301 @@ +{ + "metadata": { + "toolPackage": "@microsoft/api-extractor", + "toolVersion": "[test mode]", + "schemaVersion": 1011, + "oldestForwardsCompatibleVersion": 1001, + "tsdocConfig": { + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "noStandardTags": true, + "tagDefinitions": [ + { + "tagName": "@alpha", + "syntaxKind": "modifier" + }, + { + "tagName": "@beta", + "syntaxKind": "modifier" + }, + { + "tagName": "@defaultValue", + "syntaxKind": "block" + }, + { + "tagName": "@decorator", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@deprecated", + "syntaxKind": "block" + }, + { + "tagName": "@eventProperty", + "syntaxKind": "modifier" + }, + { + "tagName": "@example", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@experimental", + "syntaxKind": "modifier" + }, + { + "tagName": "@inheritDoc", + "syntaxKind": "inline" + }, + { + "tagName": "@internal", + "syntaxKind": "modifier" + }, + { + "tagName": "@label", + "syntaxKind": "inline" + }, + { + "tagName": "@link", + "syntaxKind": "inline", + "allowMultiple": true + }, + { + "tagName": "@override", + "syntaxKind": "modifier" + }, + { + "tagName": "@packageDocumentation", + "syntaxKind": "modifier" + }, + { + "tagName": "@param", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@privateRemarks", + "syntaxKind": "block" + }, + { + "tagName": "@public", + "syntaxKind": "modifier" + }, + { + "tagName": "@readonly", + "syntaxKind": "modifier" + }, + { + "tagName": "@remarks", + "syntaxKind": "block" + }, + { + "tagName": "@returns", + "syntaxKind": "block" + }, + { + "tagName": "@sealed", + "syntaxKind": "modifier" + }, + { + "tagName": "@see", + "syntaxKind": "block" + }, + { + "tagName": "@throws", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@typeParam", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@virtual", + "syntaxKind": "modifier" + }, + { + "tagName": "@jsx", + "syntaxKind": "block" + }, + { + "tagName": "@jsxRuntime", + "syntaxKind": "block" + }, + { + "tagName": "@jsxFrag", + "syntaxKind": "block" + }, + { + "tagName": "@jsxImportSource", + "syntaxKind": "block" + }, + { + "tagName": "@betaDocumentation", + "syntaxKind": "modifier" + }, + { + "tagName": "@internalRemarks", + "syntaxKind": "block" + }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, + { + "tagName": "@preapproved", + "syntaxKind": "modifier" + } + ], + "supportForTags": { + "@alpha": true, + "@beta": true, + "@defaultValue": true, + "@decorator": true, + "@deprecated": true, + "@eventProperty": true, + "@example": true, + "@experimental": true, + "@inheritDoc": true, + "@internal": true, + "@label": true, + "@link": true, + "@override": true, + "@packageDocumentation": true, + "@param": true, + "@privateRemarks": true, + "@public": true, + "@readonly": true, + "@remarks": true, + "@returns": true, + "@sealed": true, + "@see": true, + "@throws": true, + "@typeParam": true, + "@virtual": true, + "@betaDocumentation": true, + "@internalRemarks": true, + "@module": true, + "@preapproved": true + }, + "reportUnsupportedHtmlElements": false + } + }, + "kind": "Package", + "canonicalReference": "api-extractor-scenarios!", + "docComment": "", + "name": "api-extractor-scenarios", + "preserveMemberOrder": false, + "members": [ + { + "kind": "EntryPoint", + "canonicalReference": "api-extractor-scenarios!", + "name": "", + "preserveMemberOrder": false, + "members": [ + { + "kind": "Namespace", + "canonicalReference": "api-extractor-scenarios!Text:namespace", + "docComment": "", + "excerptTokens": [], + "fileUrlPath": "src/moduleNamespaceComment/index.ts", + "releaseTag": "None", + "name": "Text", + "preserveMemberOrder": false, + "members": [ + { + "kind": "Function", + "canonicalReference": "api-extractor-scenarios!Text.convertToCrLf:function(1)", + "docComment": "/**\n * Convert line endings to `\\r\\n`\n *\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare function convertToCrLf(input: " + }, + { + "kind": "Content", + "text": "string" + }, + { + "kind": "Content", + "text": "): " + }, + { + "kind": "Content", + "text": "string" + }, + { + "kind": "Content", + "text": ";" + } + ], + "fileUrlPath": "src/moduleNamespaceComment/Text.ts", + "returnTypeTokenRange": { + "startIndex": 3, + "endIndex": 4 + }, + "releaseTag": "Public", + "overloadIndex": 1, + "parameters": [ + { + "parameterName": "input", + "parameterTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "isOptional": false + } + ], + "name": "convertToCrLf" + }, + { + "kind": "Function", + "canonicalReference": "api-extractor-scenarios!Text.convertToLf:function(1)", + "docComment": "/**\n * Convert line endings to `\\n`\n *\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare function convertToLf(input: " + }, + { + "kind": "Content", + "text": "string" + }, + { + "kind": "Content", + "text": "): " + }, + { + "kind": "Content", + "text": "string" + }, + { + "kind": "Content", + "text": ";" + } + ], + "fileUrlPath": "src/moduleNamespaceComment/Text.ts", + "returnTypeTokenRange": { + "startIndex": 3, + "endIndex": 4 + }, + "releaseTag": "Public", + "overloadIndex": 1, + "parameters": [ + { + "parameterName": "input", + "parameterTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "isOptional": false + } + ], + "name": "convertToLf" + } + ] + } + ] + } + ] +} diff --git a/build-tests/api-extractor-scenarios/etc/moduleNamespaceComment/api-extractor-scenarios.api.md b/build-tests/api-extractor-scenarios/etc/moduleNamespaceComment/api-extractor-scenarios.api.md new file mode 100644 index 00000000000..248c155da62 --- /dev/null +++ b/build-tests/api-extractor-scenarios/etc/moduleNamespaceComment/api-extractor-scenarios.api.md @@ -0,0 +1,22 @@ +## API Report File for "api-extractor-scenarios" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts + +// @public +function convertToCrLf(input: string): string; + +// @public +function convertToLf(input: string): string; + +declare namespace Text { + export { + convertToLf, + convertToCrLf + } +} + +// (No @packageDocumentation comment for this package) + +``` diff --git a/build-tests/api-extractor-scenarios/etc/moduleNamespaceComment/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/moduleNamespaceComment/rollup.d.ts new file mode 100644 index 00000000000..7f3d2a0a82b --- /dev/null +++ b/build-tests/api-extractor-scenarios/etc/moduleNamespaceComment/rollup.d.ts @@ -0,0 +1,24 @@ +/** + * Convert line endings to `\r\n` + * @public + */ +declare function convertToCrLf(input: string): string; + +/** + * Convert line endings to `\n` + * @public + */ +declare function convertToLf(input: string): string; + +/** +* @module +* Functions for manipulating text. +*/ +export declare namespace Text { + export { + convertToLf, + convertToCrLf + } +} + +export { } diff --git a/build-tests/api-extractor-scenarios/etc/namedDefaultImport/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/namedDefaultImport/api-extractor-scenarios.api.json index 6dc01c4631a..2301d44a228 100644 --- a/build-tests/api-extractor-scenarios/etc/namedDefaultImport/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/namedDefaultImport/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/namespaceImports/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/namespaceImports/api-extractor-scenarios.api.json index c5bc0066f09..d473b950da8 100644 --- a/build-tests/api-extractor-scenarios/etc/namespaceImports/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/namespaceImports/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/namespaceImports2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/namespaceImports2/api-extractor-scenarios.api.json index ebe57a27586..b0c8e962b2c 100644 --- a/build-tests/api-extractor-scenarios/etc/namespaceImports2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/namespaceImports2/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/preapproved/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/preapproved/api-extractor-scenarios.api.json index f2997df1bb1..01d8d7ec495 100644 --- a/build-tests/api-extractor-scenarios/etc/preapproved/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/preapproved/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/projectFolderUrl/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/projectFolderUrl/api-extractor-scenarios.api.json index 87512f5600a..d0dd918b959 100644 --- a/build-tests/api-extractor-scenarios/etc/projectFolderUrl/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/projectFolderUrl/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/readonlyDeclarations/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/readonlyDeclarations/api-extractor-scenarios.api.json index c365d60a23a..1bfc100ff51 100644 --- a/build-tests/api-extractor-scenarios/etc/readonlyDeclarations/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/readonlyDeclarations/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/referenceTokens/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/referenceTokens/api-extractor-scenarios.api.json index a25d98c8424..eb0dfaef1ef 100644 --- a/build-tests/api-extractor-scenarios/etc/referenceTokens/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/referenceTokens/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/spanSorting/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/spanSorting/api-extractor-scenarios.api.json index a6a20a02af3..1afee85010f 100644 --- a/build-tests/api-extractor-scenarios/etc/spanSorting/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/spanSorting/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/typeLiterals/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/typeLiterals/api-extractor-scenarios.api.json index 4af8707d08d..7661e0544e5 100644 --- a/build-tests/api-extractor-scenarios/etc/typeLiterals/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/typeLiterals/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/typeOf/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/typeOf/api-extractor-scenarios.api.json index febcf6ccf7c..8d1ab69eb15 100644 --- a/build-tests/api-extractor-scenarios/etc/typeOf/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/typeOf/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/typeOf2/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/typeOf2/api-extractor-scenarios.api.json index ba35fe47ce2..be58fbdfbba 100644 --- a/build-tests/api-extractor-scenarios/etc/typeOf2/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/typeOf2/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/typeOf3/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/typeOf3/api-extractor-scenarios.api.json index d592718a445..a7b8071a0ad 100644 --- a/build-tests/api-extractor-scenarios/etc/typeOf3/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/typeOf3/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/etc/typeParameters/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/typeParameters/api-extractor-scenarios.api.json index ed2b317d221..acd000ac235 100644 --- a/build-tests/api-extractor-scenarios/etc/typeParameters/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/typeParameters/api-extractor-scenarios.api.json @@ -138,6 +138,10 @@ "tagName": "@internalRemarks", "syntaxKind": "block" }, + { + "tagName": "@module", + "syntaxKind": "modifier" + }, { "tagName": "@preapproved", "syntaxKind": "modifier" @@ -171,6 +175,7 @@ "@virtual": true, "@betaDocumentation": true, "@internalRemarks": true, + "@module": true, "@preapproved": true }, "reportUnsupportedHtmlElements": false diff --git a/build-tests/api-extractor-scenarios/src/moduleNamespaceComment/Text.ts b/build-tests/api-extractor-scenarios/src/moduleNamespaceComment/Text.ts new file mode 100644 index 00000000000..0de90f73b9c --- /dev/null +++ b/build-tests/api-extractor-scenarios/src/moduleNamespaceComment/Text.ts @@ -0,0 +1,23 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. +// See LICENSE in the project root for license information. + +/** + * @module + * Functions for manipulating text. + */ + +/** + * Convert line endings to `\n` + * @public + */ +export function convertToLf(input: string): string { + return input.replace(/\r\n/g, '\n'); +} + +/** + * Convert line endings to `\r\n` + * @public + */ +export function convertToCrLf(input: string): string { + return input.replace(/\r?\n/g, '\r\n'); +} diff --git a/build-tests/api-extractor-scenarios/src/moduleNamespaceComment/index.ts b/build-tests/api-extractor-scenarios/src/moduleNamespaceComment/index.ts new file mode 100644 index 00000000000..c91370a9486 --- /dev/null +++ b/build-tests/api-extractor-scenarios/src/moduleNamespaceComment/index.ts @@ -0,0 +1,4 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. +// See LICENSE in the project root for license information. + +export * as Text from './Text'; diff --git a/common/changes/@microsoft/api-extractor/module-comment-support_2025-11-19-01-23.json b/common/changes/@microsoft/api-extractor/module-comment-support_2025-11-19-01-23.json new file mode 100644 index 00000000000..14e1a7238be --- /dev/null +++ b/common/changes/@microsoft/api-extractor/module-comment-support_2025-11-19-01-23.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "@microsoft/api-extractor", + "comment": "Add support for @module comments on namespace objects. When a module is re-exported as a namespace (e.g., `export * as Foo from './Foo'`), any @module comment from the source file is now applied to the generated namespace declaration in the .d.ts rollup.", + "type": "minor" + } + ], + "packageName": "@microsoft/api-extractor", + "email": "copilot@github.com" +} diff --git a/common/reviews/api/api-extractor.api.md b/common/reviews/api/api-extractor.api.md index f44ecd8e92b..2271f7bc079 100644 --- a/common/reviews/api/api-extractor.api.md +++ b/common/reviews/api/api-extractor.api.md @@ -151,6 +151,7 @@ export enum ExtractorMessageId { IncompatibleReleaseTags = "ae-incompatible-release-tags", InternalMissingUnderscore = "ae-internal-missing-underscore", InternalMixedReleaseTag = "ae-internal-mixed-release-tag", + MisplacedModuleTag = "ae-misplaced-module-tag", MisplacedPackageTag = "ae-misplaced-package-tag", MissingGetter = "ae-missing-getter", MissingReleaseTag = "ae-missing-release-tag",