Add support for "module" comments on global files

Resolves #2165

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Unreleased
 
+### Features
+
+-   Added support for discovering a "module" comment on global files, #2165.
+
 ### Bug Fixes
 
 -   Even more contrast fixes, #2248.

src/lib/converter/comments/discovery.ts

@@ -101,6 +101,29 @@ export interface DiscoveredComment {
     jsDoc: ts.JSDoc | undefined;
 }
 
+export function discoverFileComment(
+    node: ts.SourceFile,
+    commentStyle: CommentStyle
+) {
+    const text = node.text;
+
+    const comments = collectCommentRanges(
+        ts.getLeadingCommentRanges(text, node.pos)
+    );
+
+    const selectedDocComment = comments.find((ranges) =>
+        permittedRange(text, ranges, commentStyle)
+    );
+
+    if (selectedDocComment) {
+        return {
+            file: node,
+            ranges: selectedDocComment,
+            jsDoc: findJsDocForComment(node, selectedDocComment),
+        };
+    }
+}
+
 export function discoverComment(
     symbol: ts.Symbol,
     kind: ReflectionKind,

src/lib/converter/comments/index.ts

@@ -9,6 +9,7 @@ import { lexBlockComment } from "./blockLexer";
 import {
     DiscoveredComment,
     discoverComment,
+    discoverFileComment,
     discoverSignatureComment,
 } from "./discovery";
 import { lexLineComments } from "./lineLexer";
@@ -162,6 +163,22 @@ export function getComment(
     return comment;
 }
 
+export function getFileComment(
+    file: ts.SourceFile,
+    config: CommentParserConfig,
+    logger: Logger,
+    commentStyle: CommentStyle,
+    checker: ts.TypeChecker | undefined
+): Comment | undefined {
+    return getCommentImpl(
+        discoverFileComment(file, commentStyle),
+        config,
+        logger,
+        /* moduleComment */ true,
+        checker
+    );
+}
+
 function getConstructorParamPropertyComment(
     symbol: ts.Symbol,
     config: CommentParserConfig,

src/lib/converter/context.ts

@@ -14,7 +14,12 @@ import type { Converter } from "./converter";
 import { isNamedNode } from "./utils/nodes";
 import { ConverterEvents } from "./converter-events";
 import { resolveAliasedSymbol } from "./utils/symbols";
-import { getComment, getJsDocComment, getSignatureComment } from "./comments";
+import {
+    getComment,
+    getFileComment,
+    getJsDocComment,
+    getSignatureComment,
+} from "./comments";
 import { getHumanName } from "../utils/tsutils";
 
 /**
@@ -265,6 +270,16 @@ export class Context {
         );
     }
 
+    getFileComment(node: ts.SourceFile) {
+        return getFileComment(
+            node,
+            this.converter.config,
+            this.logger,
+            this.converter.commentStyle,
+            this.converter.useTsLinkResolution ? this.checker : undefined
+        );
+    }
+
     getJsDocComment(
         declaration:
             | ts.JSDocPropertyLikeTag

src/lib/converter/converter.ts

@@ -368,8 +368,9 @@ export class Converter extends ChildableComponent<
             // Special case for when we're giving a single entry point, we don't need to
             // create modules for each entry. Register the project as this module.
             context.project.registerReflection(context.project, symbol);
-            context.project.comment =
-                symbol && context.getComment(symbol, context.project.kind);
+            context.project.comment = symbol
+                ? context.getComment(symbol, context.project.kind)
+                : context.getFileComment(node);
             context.trigger(
                 Converter.EVENT_CREATE_DECLARATION,
                 context.project
@@ -383,6 +384,10 @@ export class Converter extends ChildableComponent<
                 entryName
             );
 
+            if (!reflection.comment && !symbol) {
+                reflection.comment = context.getFileComment(node);
+            }
+
             if (entryPoint.readmeFile) {
                 const readme = readFile(entryPoint.readmeFile);
                 const comment = this.parseRawComment(

src/test/converter2/issues/gh2165.ts

@@ -0,0 +1,6 @@
+/**
+ * 'module' comment
+ * @module
+ */
+
+var globalFile = true;

src/test/issues.c2.test.ts

@@ -1008,6 +1008,14 @@ describe("Issue Tests", () => {
         );
     });
 
+    it("#2165 module comments on global files", () => {
+        const project = convert();
+        equal(
+            Comment.combineDisplayParts(project.comment?.summary),
+            "'module' comment"
+        );
+    });
+
     it("#2175", () => {
         const project = convert();
         const def = query(project, "default");