Handle @module on declare module "foo"

Resolves #2401

CHANGELOG.md

@@ -10,6 +10,7 @@
 -   Invalid link validation is now correctly suppressed before all projects have been converted in packages mode, #2403.
 -   Fixed tsconfig handling for projects using a solution-style tsconfig, #2406.
 -   Fixed broken settings icons caused by icon caching introduced in 0.25.1, #2408.
+-   Corrected module comment handling on declaration files containing a single `declare module "foo"`, #2401.
 
 ### Thanks!
 

package.json

@@ -64,7 +64,7 @@
     "test": "mocha --config .config/mocha.fast.json",
     "test:cov": "c8 mocha --config .config/mocha.fast.json",
     "doc:c": "node bin/typedoc --tsconfig src/test/converter/tsconfig.json",
-    "doc:c2": "node bin/typedoc --tsconfig src/test/converter2/tsconfig.json",
+    "doc:c2": "node --inspect-brk bin/typedoc --tsconfig src/test/converter2/tsconfig.json",
     "test:full": "c8 mocha --config .config/mocha.full.json",
     "test:visual": "ts-node ./src/test/capture-screenshots.ts && ./scripts/compare_screenshots.sh",
     "test:visual:accept": "node scripts/accept_visual_regression.js",

src/lib/converter/comments/discovery.ts

@@ -24,8 +24,14 @@ const variablePropertyKinds = [
 // the JSDoc converter because we only want part of the comment when
 // getting them.
 const wantedKinds: Record<ReflectionKind, ts.SyntaxKind[]> = {
-    [ReflectionKind.Project]: [ts.SyntaxKind.SourceFile],
-    [ReflectionKind.Module]: [ts.SyntaxKind.SourceFile],
+    [ReflectionKind.Project]: [
+        ts.SyntaxKind.SourceFile,
+        ts.SyntaxKind.ModuleDeclaration,
+    ],
+    [ReflectionKind.Module]: [
+        ts.SyntaxKind.SourceFile,
+        ts.SyntaxKind.ModuleDeclaration,
+    ],
     [ReflectionKind.Namespace]: [
         ts.SyntaxKind.ModuleDeclaration,
         ts.SyntaxKind.SourceFile,

src/lib/converter/comments/index.ts

@@ -142,11 +142,19 @@ export function getComment(
         );
     }
 
+    const isModule = declarations.some((decl) => {
+        if (ts.isSourceFile(decl)) return true;
+        if (ts.isModuleDeclaration(decl) && ts.isStringLiteral(decl.name)) {
+            return true;
+        }
+        return false;
+    });
+
     const comment = getCommentImpl(
         discoverComment(symbol, kind, logger, commentStyle),
         config,
         logger,
-        declarations.some(ts.isSourceFile),
+        isModule,
         checker,
     );
 

src/lib/converter/plugins/CommentPlugin.ts

@@ -263,7 +263,7 @@ export class CommentPlugin extends ConverterComponent {
         const comment = reflection.comment;
         if (!comment) return;
 
-        if (reflection.kindOf(ReflectionKind.Module)) {
+        if (reflection.kindOf(ReflectionKind.SomeModule)) {
             const tag = comment.getTag("@module");
             if (tag) {
                 // If no name is specified, this is a flag to mark a comment as a module comment

src/test/converter2/issues/gh2401.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Comment for module
+ * @module foo:bar
+ */
+declare module "foo:bar" {
+    export function doSomething(a: any): void;
+}

src/test/issues.c2.test.ts

@@ -1162,4 +1162,16 @@ describe("Issue Tests", () => {
             "desc",
         );
     });
+
+    // This is rather unfortunate, we need to do this so that files which include only
+    // a single declare module can still have a comment on them, but it looks really
+    // weird and wrong if there are multiple declare module statements in a file...
+    // there's probably some nicer way of doing this that I'm not seeing right now.
+    it("Uses module comment discovery on 'declare module \"foo\"' #2401", () => {
+        const project = convert();
+        equal(
+            Comment.combineDisplayParts(project.comment?.summary),
+            "Comment for module",
+        );
+    });
 });