Always filter for module comments

Fixes #1962
TypeStrong · Jun 27, 2022 · c6011cc · c6011cc
1 parent dc23d40
commit c6011cc
Show file tree

Hide file tree

Showing 4 changed files with 41 additions and 73 deletions.
diff --git a/src/lib/converter/comments/index.ts b/src/lib/converter/comments/index.ts
@@ -61,20 +61,15 @@ function getCommentWithCache(
     return comment.clone();
 }
 
-export function getComment(
-    symbol: ts.Symbol,
-    kind: ReflectionKind,
+function getCommentImpl(
+    commentSource: [ts.SourceFile, ts.CommentRange[]] | undefined,
     config: CommentParserConfig,
     logger: Logger,
-    commentStyle: CommentStyle
-): Comment | undefined {
-    const comment = getCommentWithCache(
-        discoverComment(symbol, kind, logger, commentStyle),
-        config,
-        logger
-    );
+    moduleComment: boolean
+) {
+    const comment = getCommentWithCache(commentSource, config, logger);
 
-    if (symbol.declarations?.some(ts.isSourceFile) && comment) {
+    if (moduleComment && comment) {
         // Module comment, make sure it is tagged with @packageDocumentation or @module.
         // If it isn't then the comment applies to the first statement in the file, so throw it away.
         if (
@@ -85,7 +80,7 @@ export function getComment(
         }
     }
 
-    if (!symbol.declarations?.some(ts.isSourceFile) && comment) {
+    if (!moduleComment && comment) {
         // Ensure module comments are not attached to non-module reflections.
         if (
             comment.hasModifier("@packageDocumentation") ||
@@ -98,16 +93,32 @@ export function getComment(
     return comment;
 }
 
+export function getComment(
+    symbol: ts.Symbol,
+    kind: ReflectionKind,
+    config: CommentParserConfig,
+    logger: Logger,
+    commentStyle: CommentStyle
+): Comment | undefined {
+    return getCommentImpl(
+        discoverComment(symbol, kind, logger, commentStyle),
+        config,
+        logger,
+        symbol.declarations?.some(ts.isSourceFile) || false
+    );
+}
+
 export function getSignatureComment(
     declaration: ts.SignatureDeclaration | ts.JSDocSignature,
     config: CommentParserConfig,
     logger: Logger,
     commentStyle: CommentStyle
 ): Comment | undefined {
-    return getCommentWithCache(
+    return getCommentImpl(
         discoverSignatureComment(declaration, commentStyle),
         config,
-        logger
+        logger,
+        false
     );
 }
 

diff --git a/src/test/converter/comment/specs.json b/src/test/converter/comment/specs.json
@@ -237,25 +237,6 @@
               "kind": 4096,
               "kindString": "Call signature",
               "flags": {},
-              "comment": {
-                "summary": [
-                  {
-                    "kind": "text",
-                    "text": "This is a module doc with the packageDocumentation tag to mark it as documentation\nfor the whole module. It is *not* documentation for the "
-                  },
-                  {
-                    "kind": "code",
-                    "text": "`multiply`"
-                  },
-                  {
-                    "kind": "text",
-                    "text": " function."
-                  }
-                ],
-                "modifierTags": [
-                  "@packageDocumentation"
-                ]
-              },
               "parameters": [
                 {
                   "id": 29,
@@ -349,28 +330,6 @@
               "kind": 4096,
               "kindString": "Call signature",
               "flags": {},
-              "comment": {
-                "summary": [
-                  {
-                    "kind": "text",
-                    "text": "This is a module doc with the module tag to mark it as documentation\nfor the whole module. It is *not* documentation for the "
-                  },
-                  {
-                    "kind": "code",
-                    "text": "`multiply`"
-                  },
-                  {
-                    "kind": "text",
-                    "text": " function."
-                  }
-                ],
-                "blockTags": [
-                  {
-                    "tag": "@module",
-                    "content": []
-                  }
-                ]
-              },
               "parameters": [
                 {
                   "id": 34,
@@ -460,24 +419,6 @@
               "kind": 4096,
               "kindString": "Call signature",
               "flags": {},
-              "comment": {
-                "summary": [
-                  {
-                    "kind": "text",
-                    "text": "This is a comment containing a multiline code block\n"
-                  },
-                  {
-                    "kind": "code",
-                    "text": "```ts\nexport function multiply(a: number, b: number) {\n  return a * b;\n}\n```"
-                  }
-                ],
-                "blockTags": [
-                  {
-                    "tag": "@module",
-                    "content": []
-                  }
-                ]
-              },
               "parameters": [
                 {
                   "id": 39,

diff --git a/src/test/converter2/issues/gh1962.ts b/src/test/converter2/issues/gh1962.ts
@@ -0,0 +1,5 @@
+/**
+ * Documented module
+ * @module
+ */
+export function foo() {}
diff --git a/src/test/issueTests.ts b/src/test/issueTests.ts
@@ -525,4 +525,15 @@ export const issueTests: {
             "second"
         );
     },
+
+    gh1962(project) {
+        const foo = query(project, "foo");
+        ok(foo.signatures);
+        // #1963
+        // ok(project.hasComment(), "Missing module comment");
+        ok(
+            !foo.signatures[0].hasComment(),
+            "Module comment attached to signature"
+        );
+    },
 };