fix: Split out comment summary and tags for signatures

typedoc2md · Jul 24, 2023 · 2e69aed · 2e69aed
1 parent 4875a02
commit 2e69aed
Show file tree

Hide file tree

Showing 4 changed files with 59 additions and 16 deletions.
diff --git a/packages/typedoc-plugin-markdown/src/resources/helpers/comments.ts b/packages/typedoc-plugin-markdown/src/resources/helpers/comments.ts
@@ -3,25 +3,30 @@ import { Comment } from 'typedoc';
 import { camelToTitleCase } from '../../utils';
 
 export default function () {
-  Handlebars.registerHelper('comments', function (comment: Comment) {
-    const md: string[] = [];
+  Handlebars.registerHelper(
+    'comments',
+    function (comment: Comment, showSummary = true, showTags = true) {
+      const md: string[] = [];
 
-    if (comment.summary) {
-      md.push(Handlebars.helpers.comment(comment.summary));
-    }
+      if (showSummary && comment.summary) {
+        md.push(Handlebars.helpers.comment(comment.summary));
+      }
 
-    if (comment.blockTags?.length) {
-      const tags = comment.blockTags
-        .filter((tag) => tag.tag !== '@returns')
-        .map(
+      const filteredTags = comment.blockTags.filter(
+        (tag) => tag.tag !== '@returns',
+      );
+
+      if (showTags && comment.blockTags?.length) {
+        const tags = filteredTags.map(
           (tag) =>
             `**\`${camelToTitleCase(
               tag.tag.substring(1),
             )}\`**\n\n${Handlebars.helpers.comment(tag.content)}`,
         );
-      md.push(tags.join('\n\n'));
-    }
+        md.push(tags.join('\n\n'));
+      }
 
-    return md.join('\n\n');
-  });
+      return md.join('\n\n');
+    },
+  );
 }
diff --git a/packages/typedoc-plugin-markdown/src/resources/partials/member.signature.hbs b/packages/typedoc-plugin-markdown/src/resources/partials/member.signature.hbs
@@ -1,6 +1,14 @@
 {{{signatureTitle accessor}}}
 
-{{> comment}}
+{{#with comment}}
+
+{{#if hasVisibleComponent}}
+
+{{{comments this true false}}}
+
+{{/if}}
+
+{{/with}}
 
 {{#if typeParameters}}
 
@@ -96,6 +104,16 @@
 
 {{/ifShowReturns}}
 
+{{#with comment}}
+
+{{#if hasVisibleComponent}}
+
+{{{comments this false true}}}
+
+{{/if}}
+
+{{/with}}
+
 {{#if showSources}}
 
 {{> member.sources}}

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/generics.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/generics.spec.ts.snap
@@ -23,8 +23,6 @@ exports[`Generics: should compile class with type params 1`] = `
 exports[`Generics: should compile function with a simple type param' 1`] = `
 "▸ **functionWithTypeParam**<\`A\`\\>(): \`boolean\`
 
-[partial: comment]
-
 ##### Type parameters
 
 | Name |

diff --git a/stub-project/src/comments.ts b/stub-project/src/comments.ts
@@ -108,3 +108,25 @@ export type literalWithBlockComments = {
    */
   prop: string;
 };
+
+/**
+ * Creates an integer expression for the end of an interval variable.
+ *
+ * @remarks
+ *
+ * If the interval is absent then the resulting expression is also absent.
+ *
+ * @example
+ *
+ * In the following example we constraint interval variable `y` to start after end of `y` with a delay at least 10. In addition we constrain length of `x` to be less or equal than length of `y`.
+ *
+ * ```ts
+ * let model = new CP.Model;
+ * ```
+ *
+ * When `x` or `y` is _absent_ then value of both constraints above is _absent_ and therefore they are satisfied.
+ *
+ */
+export function functionWithSummaryAndTags(arg: any) {
+  return '';
+}