fix(core): correctly resolve comment summary for const functions

typedoc2md · Jul 22, 2024 · 58d2d3c · 58d2d3c
1 parent da03942
commit 58d2d3c
Show file tree

Hide file tree

Showing 6 changed files with 125 additions and 13 deletions.
diff --git a/.changeset/great-comics-notice.md b/.changeset/great-comics-notice.md
@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-markdown': patch
+---
+
+- Correctly resolve comment summary for const functions (#656)
diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signature.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signature.ts
@@ -22,7 +22,22 @@ export function signature(
     );
   }
 
-  const modelComments = model.comment || model.parent?.comment;
+  let modelComments = model.comment || model.parent?.comment;
+
+  if (
+    modelComments &&
+    model.parent?.comment?.summary &&
+    !options.multipleSignatures
+  ) {
+    modelComments = Object.assign(modelComments, {
+      summary: model.parent.comment.summary,
+    });
+  }
+  if (modelComments && model.parent?.comment?.blockTags) {
+    modelComments = Object.assign(modelComments, {
+      blockTags: model.parent.comment.blockTags,
+    });
+  }
 
   if (modelComments) {
     md.push(

diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts
@@ -141,11 +141,37 @@ export function multipleExampleTags() {
  * ```ts
  * factorial(1)
  * ```
+ *
+ * @returns Return comments
  */
 export function singleExampleTag() {
   return true;
 }
 
+/**
+ * constFunction comments
+ *
+ * @param text Some param
+ *
+ * @remarks Some remarks
+ */
+export const constFunction = (text: string) => {
+  return true;
+};
+
+/**
+ * constFunctionWithReturns comments
+ *
+ * @param text Some param
+ *
+ * @returns Return comments
+ *
+ * @remarks Some remarks
+ */
+export const constFunctionWithReturns = (text: string) => {
+  return true;
+};
+
 export class BaseClassProperties {
   /**
    * @deprecated

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap
@@ -119,6 +119,8 @@ Some <p> html </p> inside codeblock
 
 ## Functions
 
+- [constFunction](functions/constFunction.md)
+- [constFunctionWithReturns](functions/constFunctionWithReturns.md)
 - [functionWithBlockTags](functions/functionWithBlockTags.md)
 - [multipleExampleTags](functions/multipleExampleTags.md)
 - [parametersTable](functions/parametersTable.md)
@@ -724,6 +726,60 @@ Other block tags
 "
 `;
 
+exports[`Comments should handle const function with returns: (Output File Strategy "members") (Option Group "1") 1`] = `
+"# Function: constFunctionWithReturns()
+
+> **constFunctionWithReturns**(\`text\`): \`boolean\`
+
+constFunctionWithReturns comments
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| \`text\` | \`string\` | Some param |
+
+## Returns
+
+\`boolean\`
+
+## Remarks
+
+Some remarks
+
+## Source
+
+[index.ts:1](http://source-url)
+"
+`;
+
+exports[`Comments should handle const function: (Output File Strategy "members") (Option Group "1") 1`] = `
+"# Function: constFunction()
+
+> **constFunction**(\`text\`): \`boolean\`
+
+constFunction comments
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| \`text\` | \`string\` | Some param |
+
+## Returns
+
+\`boolean\`
+
+## Remarks
+
+Some remarks
+
+## Source
+
+[index.ts:1](http://source-url)
+"
+`;
+
 exports[`Comments should handle multiple example tags: (Output File Strategy "members") (Option Group "1") 1`] = `
 "# Function: multipleExampleTags()
 
@@ -759,25 +815,19 @@ factorial(1)
 `;
 
 exports[`Comments should handle single example tags: (Output File Strategy "members") (Option Group "1") 1`] = `
-"# Function: multipleExampleTags()
+"# Function: singleExampleTag()
 
-> **multipleExampleTags**(): \`boolean\`
+> **singleExampleTag**(): \`boolean\`
 
-Function with multiple example tags
+Function with single example tag
 
 ## Returns
 
 \`boolean\`
 
-## Examples
+Return comments
 
-\`\`\`ts
-// If there are no code blocks, TypeDoc assumes the whole tag
-// should be a code block. This is not valid TSDoc, but is recognized
-// by VSCode and enables better JSDoc support.
-
-factorial(1)
-\`\`\`
+## Example
 
 If there is a code block, then both TypeDoc and VSCode will treat
 text outside of the code block as regular text.

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap
@@ -965,6 +965,8 @@ exports[`Urls should gets Urls with media assets: outputFileStrategy: members 1`
   "classes/ClassPropertiesTable.md",
   "enumerations/CommentEnum.md",
   "enumerations/EnumMembersTable.md",
+  "functions/constFunction.md",
+  "functions/constFunctionWithReturns.md",
   "functions/functionWithBlockTags.md",
   "functions/multipleExampleTags.md",
   "functions/parametersTable.md",
@@ -991,6 +993,8 @@ exports[`Urls should gets Urls with media assets: outputFileStrategy: members 2`
   "Class.ClassPropertiesTable.md",
   "Enumeration.CommentEnum.md",
   "Enumeration.EnumMembersTable.md",
+  "Function.constFunction.md",
+  "Function.constFunctionWithReturns.md",
   "Function.functionWithBlockTags.md",
   "Function.multipleExampleTags.md",
   "Function.parametersTable.md",

diff --git a/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts b/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts
@@ -13,7 +13,7 @@ describe(`Comments`, () => {
     expectFileToEqual(
       'comments',
       ['members'],
-      ['/functions/multipleExampleTags.md'],
+      ['/functions/singleExampleTag.md'],
     );
   });
 
@@ -25,6 +25,18 @@ describe(`Comments`, () => {
     );
   });
 
+  test(`should handle const function`, () => {
+    expectFileToEqual('comments', ['members'], ['/functions/constFunction.md']);
+  });
+
+  test(`should handle const function with returns`, () => {
+    expectFileToEqual(
+      'comments',
+      ['members'],
+      ['/functions/constFunctionWithReturns.md'],
+    );
+  });
+
   test(`should get tables for properties`, () => {
     expectFileToEqual('comments', 'members', [
       '/classes/ClassPropertiesTable.md',