Add @module comment support to namespace declarations

- Added @module tag definition to TSDoc configuration
- Created ModuleDocComment helper to extract @module comments
- Modified DtsRollupGenerator to apply @module comments to namespaces
- Added logic to skip @module comments on regular declarations
- Created test case moduleNamespaceComment to verify functionality

Co-authored-by: iclanton <[email protected]>

Author: Copilot

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,

apps/api-extractor/src/aedoc/ModuleDocComment.ts

@@ -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 {
+  /**
+   * 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;
+  }
+}

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,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 ');
         }
@@ -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();
+        }
+
         // For now, we don't transform JSDoc comment nodes at all
         recurseChildren = false;
         break;

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

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

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

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

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

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

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