Prefer placing comment on function signature

This is specific to variable-functions, and is a balance between
having comments supported on function declarations
and comments preferring the signature to be more
consistent with how regular function declarations work.

Resolves #2824

Author: Gerrit0

CHANGELOG.md

@@ -24,6 +24,7 @@ title: Changelog
 - Introduced `packagesRequiringDocumentation` option for `validation.notDocumented`, TypeDoc will expect comments to be present for symbols in the specified packages.
 - TypeDoc's `--entryPointStrategy merge` mode now requires JSON from at least version 0.28.0.
 - TypeDoc now exports a `typedoc/browser` entrypoint for parsing and using serialized JSON files, #2528.
+- Variable-functions will now prefer placing the comment on the signature if there is only one signature present, #2824.
 
 TODO:
 

src/lib/converter/symbols.ts

@@ -1145,6 +1145,18 @@ function convertVariableAsFunction(
         );
     }
 
+    // #2824 If there is only one signature, and there isn't a comment
+    // on the signature already, treat the comment on the variable
+    // as if it belongs to the signature instead.
+    if (
+        reflection.signatures.length === 1 &&
+        !reflection.signatures[0].comment &&
+        reflection.comment
+    ) {
+        reflection.signatures[0].comment = reflection.comment;
+        delete reflection.comment;
+    }
+
     return (
         convertFunctionProperties(context.withScope(reflection), symbol, type) |
         ts.SymbolFlags.Property

src/test/converter/function/specs.json

@@ -1941,14 +1941,6 @@
                     "variant": "declaration",
                     "kind": 64,
                     "flags": {},
-                    "comment": {
-                        "summary": [
-                            {
-                                "kind": "text",
-                                "text": "This is a function that is assigned to a variable."
-                            }
-                        ]
-                    },
                     "sources": [
                         {
                             "fileName": "function.ts",
@@ -1965,7 +1957,12 @@
                             "kind": 4096,
                             "flags": {},
                             "comment": {
-                                "summary": [],
+                                "summary": [
+                                    {
+                                        "kind": "text",
+                                        "text": "This is a function that is assigned to a variable."
+                                    }
+                                ],
                                 "blockTags": [
                                     {
                                         "tag": "@returns",

src/test/converter/mixin/specs.json

@@ -1572,14 +1572,6 @@
             "variant": "declaration",
             "kind": 64,
             "flags": {},
-            "comment": {
-                "summary": [
-                    {
-                        "kind": "text",
-                        "text": "The \"mixin function\" of the Mixin1"
-                    }
-                ]
-            },
             "sources": [
                 {
                     "fileName": "mixin.ts",
@@ -1595,6 +1587,14 @@
                     "variant": "signature",
                     "kind": 4096,
                     "flags": {},
+                    "comment": {
+                        "summary": [
+                            {
+                                "kind": "text",
+                                "text": "The \"mixin function\" of the Mixin1"
+                            }
+                        ]
+                    },
                     "sources": [
                         {
                             "fileName": "mixin.ts",
@@ -1751,14 +1751,6 @@
             "variant": "declaration",
             "kind": 64,
             "flags": {},
-            "comment": {
-                "summary": [
-                    {
-                        "kind": "text",
-                        "text": "The \"mixin function\" of the Mixin2"
-                    }
-                ]
-            },
             "sources": [
                 {
                     "fileName": "mixin.ts",
@@ -1774,6 +1766,14 @@
                     "variant": "signature",
                     "kind": 4096,
                     "flags": {},
+                    "comment": {
+                        "summary": [
+                            {
+                                "kind": "text",
+                                "text": "The \"mixin function\" of the Mixin2"
+                            }
+                        ]
+                    },
                     "sources": [
                         {
                             "fileName": "mixin.ts",
@@ -1941,14 +1941,6 @@
             "variant": "declaration",
             "kind": 64,
             "flags": {},
-            "comment": {
-                "summary": [
-                    {
-                        "kind": "text",
-                        "text": "The \"mixin function\" of the Mixin3"
-                    }
-                ]
-            },
             "sources": [
                 {
                     "fileName": "mixin.ts",
@@ -1970,6 +1962,14 @@
                     "variant": "signature",
                     "kind": 4096,
                     "flags": {},
+                    "comment": {
+                        "summary": [
+                            {
+                                "kind": "text",
+                                "text": "The \"mixin function\" of the Mixin3"
+                            }
+                        ]
+                    },
                     "sources": [
                         {
                             "fileName": "mixin.ts",

src/test/issues.c2.test.ts

@@ -374,7 +374,7 @@ describe("Issue Tests", () => {
             querySig(project, "bar"),
         ].map((r) => Comment.combineDisplayParts(r.comment?.summary));
 
-        equal(comments, ["bar", "metadata", "fn", ""]);
+        equal(comments, ["", "metadata", "fn", "bar"]);
     });
 
     it("#1660", () => {
@@ -429,7 +429,7 @@ describe("Issue Tests", () => {
 
     it("#1770", () => {
         const project = convert();
-        const sym1 = query(project, "sym1");
+        const sym1 = querySig(project, "sym1");
         equal(
             Comment.combineDisplayParts(sym1.comment?.summary),
             "Docs for Sym1",
@@ -670,7 +670,7 @@ describe("Issue Tests", () => {
 
         equal(comments, ["A override", "B module"]);
 
-        const comments2 = ["A.a", "B.b"].map((n) => Comment.combineDisplayParts(query(project, n).comment?.summary));
+        const comments2 = ["A.a", "B.b"].map((n) => Comment.combineDisplayParts(querySig(project, n).comment?.summary));
 
         equal(comments2, ["Comment for a", "Comment for b"]);
     });
@@ -742,7 +742,7 @@ describe("Issue Tests", () => {
 
     it("#2008", () => {
         const project = convert();
-        const fn = query(project, "myFn");
+        const fn = querySig(project, "myFn");
         equal(Comment.combineDisplayParts(fn.comment?.summary), "Docs");
     });
 
@@ -957,8 +957,7 @@ describe("Issue Tests", () => {
     it("#2156", () => {
         app.options.setValue("excludeNotDocumented", true);
         const project = convert();
-        const foo = query(project, "foo");
-        equal(foo.signatures?.length, 1);
+        const foo = querySig(project, "foo");
         equal(
             Comment.combineDisplayParts(foo.comment?.summary),
             "Is documented",
@@ -1568,7 +1567,7 @@ describe("Issue Tests", () => {
         equal(getComment(project, "f32"), "f32 comment");
         equal(getComment(project, "f32.a"), "A comment");
         equal(getComment(project, "f32.a.member"), "Member comment");
-        equal(getComment(project, "f32.a.fn"), "Fn comment");
+        equal(getSigComment(project, "f32.a.fn"), "Fn comment");
         equal(getComment(project, "f32.b"), "B comment");
     });