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',