diff --git a/.changeset/large-lemons-hammer.md b/.changeset/large-lemons-hammer.md index 3843e244b..7e59f97cc 100644 --- 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 index 9a1e42b71..fac6e611a 100644 --- 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 index 2502a66c6..02d5116a6 100644 --- 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 index 24969b441..056fbde57 100644 --- 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 index 279954e82..011e9ba5a 100644 --- 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 + + + +### 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) +\`\`\` " `; 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 index 87de673dd..858ba0882 100644 --- 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**
This prop is deprecte

**Some Tag**
Comments for some tag | +| ~~\`deprecatedProp\`~~ | \`string\` | **Deprecated**
This prop is deprecated

**Some Tag**
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 index 9837f2d6a..729433f3f 100644 --- 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**
This prop is deprecte

**Some Tag**
Comments for some tag | +| ~~\`deprecatedProp\`~~ | \`string\` | **Deprecated**
This prop is deprecated

**Some Tag**
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**
This prop is deprecte

**Some Tag**
Comments for some tag | [\`BasicInterface\`](BasicInterface.md).\`deprecatedProp\` | +| ~~\`deprecatedProp\`~~ | \`string\` | **Deprecated**
This prop is deprecated

**Some Tag**
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\` |