fix(core): handle multiple @example tags on same reflection

typedoc2md · May 6, 2024 · 5afbeeb · 5afbeeb
1 parent a78173f
commit 5afbeeb
Show file tree

Hide file tree

Showing 7 changed files with 186 additions and 9 deletions.
diff --git a/.changeset/large-lemons-hammer.md b/.changeset/large-lemons-hammer.md
@@ -3,3 +3,4 @@
 ---
 
 - Remove superfluous newlines from table column descriptions (#591).
+- Handle multiple `@example` tags on same reflection.
diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/comments.comment.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/comments.comment.ts
@@ -2,7 +2,7 @@ import { bold, heading } from '@plugin/libs/markdown';
 import { camelToTitleCase, formatTableColumn } from '@plugin/libs/utils';
 import { sanitizeComments } from '@plugin/libs/utils/sanitize-comments';
 import { MarkdownThemeContext } from '@plugin/theme';
-import { Comment } from 'typedoc';
+import { Comment, CommentTag } from 'typedoc';
 
 /**
  * @category Comment Partials
@@ -32,7 +32,32 @@ export function comment(
   }
 
   if (opts.showTags && model.blockTags?.length) {
-    const tags = model.blockTags
+    const blockTags = model.blockTags.reduce(
+      (previous: CommentTag[], current: CommentTag) => {
+        if (current.tag === '@example') {
+          const prevExampleTag = previous.find((tag) =>
+            ['@example', '@examples'].includes(tag.tag),
+          );
+          if (prevExampleTag) {
+            return previous.map((prevTag) => {
+              if (prevTag === prevExampleTag) {
+                current.content.unshift({ kind: 'text', text: '\n\n' });
+                return {
+                  ...prevTag,
+                  tag: '@examples',
+                  content: [...prevTag.content, ...current.content],
+                };
+              }
+              return prevTag;
+            });
+          }
+        }
+        return [...previous, current];
+      },
+      [],
+    );
+
+    const tags = blockTags
       .filter((tag) => tag.tag !== '@returns')
       .filter(
         (tag) =>

diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts
@@ -103,3 +103,40 @@ export const SameName = true;
 export const prop = true;
 export const propb = true;
 export const _prop_with_underscore = true;
+
+/**
+ * Function with multiple example tags
+ *
+ * @example
+ * // 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.
+ *
+ * ```ts
+ * factorial(1)
+ * ```
+ */
+export function multipleExampleTags() {
+  return true;
+}
+
+/**
+ * Function with single example tag
+ *
+ * @example
+ * If there is a code block, then both TypeDoc and VSCode will treat
+ * text outside of the code block as regular text.
+ *
+ * ```ts
+ * factorial(1)
+ * ```
+ */
+export function singleExampleTag() {
+  return true;
+}
diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/interfaces.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/interfaces.ts
@@ -16,7 +16,7 @@ export interface BasicInterface {
   /**
    * @deprecated
    *
-   * This prop is deprecte
+   * This prop is deprecated
    *
    * @someTag
    *

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
@@ -92,6 +92,11 @@ This is a simple example on how to use include.
 - [\\_prop\\_with\\_underscore](variables/prop_with_underscore.md)
 - [prop](variables/prop.md)
 - [propb](variables/propb.md)
+
+## Functions
+
+- [multipleExampleTags](functions/multipleExampleTags.md)
+- [singleExampleTag](functions/singleExampleTag.md)
 "
 `;
 
@@ -187,6 +192,11 @@ This is a simple example on how to use include.
 - [\\_prop\\_with\\_underscore](/some-path/variables/prop_with_underscore.mdx)
 - [prop](/some-path/variables/prop.mdx)
 - [propb](/some-path/variables/propb.mdx)
+
+## Functions
+
+- [multipleExampleTags](/some-path/functions/multipleExampleTags.mdx)
+- [singleExampleTag](/some-path/functions/singleExampleTag.mdx)
 "
 `;
 
@@ -342,6 +352,56 @@ This is a simple example on how to use include.
 ### propb
 
 > \`const\` **propb**: \`true\` = \`true\`
+
+## Functions
+
+### multipleExampleTags()
+
+> **multipleExampleTags**(): \`boolean\`
+
+Function with multiple example tags
+
+#### Returns
+
+\`boolean\`
+
+#### Examples
+
+\`\`\`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)
+\`\`\`
+
+If there is a code block, then both TypeDoc and VSCode will treat
+text outside of the code block as regular text.
+
+\`\`\`ts
+factorial(1)
+\`\`\`
+
+***
+
+### singleExampleTag()
+
+> **singleExampleTag**(): \`boolean\`
+
+Function with single example tag
+
+#### Returns
+
+\`boolean\`
+
+#### Example
+
+If there is a code block, then both TypeDoc and VSCode will treat
+text outside of the code block as regular text.
+
+\`\`\`ts
+factorial(1)
+\`\`\`
 "
 `;
 
@@ -513,5 +573,59 @@ This is a simple example on how to use include.
 ### propb
 
 > \`const\` **propb**: \`true\` = \`true\`
+
+## Functions
+
+<a id="multipleExampleTags" name="multipleExampleTags"></a>
+
+### multipleExampleTags()
+
+> **multipleExampleTags**(): \`boolean\`
+
+Function with multiple example tags
+
+#### Returns
+
+\`boolean\`
+
+#### Examples
+
+\`\`\`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)
+\`\`\`
+
+If there is a code block, then both TypeDoc and VSCode will treat
+text outside of the code block as regular text.
+
+\`\`\`ts
+factorial(1)
+\`\`\`
+
+***
+
+<a id="singleExampleTag" name="singleExampleTag"></a>
+
+### singleExampleTag()
+
+> **singleExampleTag**(): \`boolean\`
+
+Function with single example tag
+
+#### Returns
+
+\`boolean\`
+
+#### Example
+
+If there is a code block, then both TypeDoc and VSCode will treat
+text outside of the code block as regular text.
+
+\`\`\`ts
+factorial(1)
+\`\`\`
 "
 `;
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/objects-and-params.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/objects-and-params.spec.ts.snap
@@ -17,7 +17,7 @@ Comments for BasicInterface
 
 #### Deprecated
 
-This prop is deprecte
+This prop is deprecated
 
 #### Some Tag
 
@@ -204,7 +204,7 @@ Comments for BasicInterface
 
 | Property | Type | Description |
 | :------ | :------ | :------ |
-| ~~\`deprecatedProp\`~~ | \`string\` | **Deprecated**<br />This prop is deprecte<br /><br />**Some Tag**<br />Comments for some tag |
+| ~~\`deprecatedProp\`~~ | \`string\` | **Deprecated**<br />This prop is deprecated<br /><br />**Some Tag**<br />Comments for some tag |
 | \`functionProp\` | (\`s\`: \`string\`) => \`boolean\` | Comments for functionProper |
 | \`optionalProp?\` | \`string\` | Comments for optional prop |
 | \`prop\` | \`string\` | Comments for prop |

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.interface.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.interface.spec.ts.snap
@@ -17,7 +17,7 @@ Comments for BasicInterface
 
 #### Deprecated
 
-This prop is deprecte
+This prop is deprecated
 
 #### Some Tag
 
@@ -244,7 +244,7 @@ Comments for BasicInterface
 
 | Property | Type | Description |
 | :------ | :------ | :------ |
-| ~~\`deprecatedProp\`~~ | \`string\` | **Deprecated**<br />This prop is deprecte<br /><br />**Some Tag**<br />Comments for some tag |
+| ~~\`deprecatedProp\`~~ | \`string\` | **Deprecated**<br />This prop is deprecated<br /><br />**Some Tag**<br />Comments for some tag |
 | \`functionProp\` | (\`s\`: \`string\`) => \`boolean\` | Comments for functionProper |
 | \`optionalProp?\` | \`string\` | Comments for optional prop |
 | \`prop\` | \`string\` | Comments for prop |
@@ -282,7 +282,7 @@ Comments for ExtendedInterface
 
 #### Deprecated
 
-This prop is deprecte
+This prop is deprecated
 
 #### Some Tag
 
@@ -559,7 +559,7 @@ Comments for ExtendedInterface
 
 | Property | Type | Description | Inherited from |
 | :------ | :------ | :------ | :------ |
-| ~~\`deprecatedProp\`~~ | \`string\` | **Deprecated**<br />This prop is deprecte<br /><br />**Some Tag**<br />Comments for some tag | [\`BasicInterface\`](BasicInterface.md).\`deprecatedProp\` |
+| ~~\`deprecatedProp\`~~ | \`string\` | **Deprecated**<br />This prop is deprecated<br /><br />**Some Tag**<br />Comments for some tag | [\`BasicInterface\`](BasicInterface.md).\`deprecatedProp\` |
 | \`extendedProp\` | \`string\` | - | - |
 | \`functionProp\` | (\`s\`: \`string\`) => \`boolean\` | Comments for functionProper | [\`BasicInterface\`](BasicInterface.md).\`functionProp\` |
 | \`optionalProp?\` | \`string\` | Comments for optional prop | [\`BasicInterface\`](BasicInterface.md).\`optionalProp\` |