From bf0dab1a53c1b3e638d51cd614be831b085dda63 Mon Sep 17 00:00:00 2001 From: tgreyuk Date: Tue, 25 Jun 2024 23:29:51 +0100 Subject: [PATCH] chore(refactor): moved comment parts to helper file --- .../helpers/get-description-for-reflection.ts | 4 +- .../src/theme/context/partials/_index.ts | 1 - .../context/partials/comments.comment.ts | 2 +- .../context/partials/comments.commentParts.ts | 70 ------------------- .../context/partials/container.categories.ts | 2 +- .../context/partials/container.groups.ts | 4 +- .../partials/member.reflectionIndex.ts | 4 +- .../context/partials/member.signature.ts | 4 +- .../partials/member.signatureReturns.ts | 2 +- .../src/theme/context/resources.ts | 2 - .../src/theme/context/templates/document.ts | 2 +- .../src/theme/context/templates/project.ts | 8 +-- .../src/theme/context/templates/read-me.ts | 2 +- .../src/theme/context/templates/reflection.ts | 6 +- .../src/theme/markdown-themeContext.ts | 11 ++- .../fixtures/src/reflections/functions.ts | 2 + .../reflection.function.spec.ts.snap | 8 +++ 17 files changed, 34 insertions(+), 100 deletions(-) delete mode 100644 packages/typedoc-plugin-markdown/src/theme/context/partials/comments.commentParts.ts diff --git a/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-description-for-reflection.ts b/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-description-for-reflection.ts index 6b4e34c7..15865082 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-description-for-reflection.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-description-for-reflection.ts @@ -9,8 +9,8 @@ export function getDescriptionForReflection( ? model.signatures[0].comment : model.comment; if (comment?.summary?.length) { - return this.partials - .commentParts(comment.summary) + return this.helpers + .getCommentParts(comment.summary) ?.split('\n\n')[0] .replace(/\n/g, ' '); } diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/_index.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/_index.ts index da496617..b30076b7 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/partials/_index.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/partials/_index.ts @@ -1,5 +1,4 @@ export * from './comments.comment'; -export * from './comments.commentParts'; export * from './container.body'; export * from './container.categories'; export * from './container.groups'; diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/comments.comment.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/comments.comment.ts index aad688fa..76886749 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/partials/comments.comment.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/partials/comments.comment.ts @@ -94,7 +94,7 @@ export function comment( ? heading(opts.headingLevel, tagText) + '\n' : bold(tagText) + '\n', ]; - tagMd.push(this.partials.commentParts(tag.content)); + tagMd.push(this.helpers.getCommentParts(tag.content)); return tagMd.join('\n'); }); md.push(tags.join('\n\n')); diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/comments.commentParts.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/comments.commentParts.ts deleted file mode 100644 index 9e776fdb..00000000 --- a/packages/typedoc-plugin-markdown/src/theme/context/partials/comments.commentParts.ts +++ /dev/null @@ -1,70 +0,0 @@ -import * as fs from 'fs'; -import { link } from 'libs/markdown'; -import { MarkdownThemeContext } from 'theme'; -import { CommentDisplayPart, InlineTagDisplayPart } from 'typedoc'; - -export function commentParts( - this: MarkdownThemeContext, - model: CommentDisplayPart[], -): string { - const md: string[] = []; - for (const part of model) { - switch (part.kind) { - case 'text': - md.push(part.text); - break; - case 'code': - md.push(part.text); - break; - case 'inline-tag': - switch (part.tag) { - case '@label': - case '@inheritdoc': - break; - case '@link': - case '@linkcode': - case '@linkplain': { - if (part.target) { - const url = getUrl(part); - const wrap = part.tag === '@linkcode' ? '`' : ''; - md.push( - url - ? `${link(`${wrap}${part.text}${wrap}`, this.getRelativeUrl(url))}` - : part.text, - ); - } else { - md.push(part.text); - } - break; - } - default: - md.push(`{${part.tag} ${part.text}}`); - break; - } - break; - default: - md.push(''); - } - } - return md.join(''); -} - -function getUrl(part: InlineTagDisplayPart) { - if ((part.target as any).url) { - return (part.target as any).url; - } - - if ((part.target as any)?.parent?.url) { - return (part.target as any)?.parent?.url; - } - - return typeof part.target === 'string' ? part.target : ''; -} - -export function isFile(file: string) { - try { - return fs.statSync(file).isFile(); - } catch { - return false; - } -} diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/container.categories.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/container.categories.ts index bb6a81de..6d8e51d9 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/partials/container.categories.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/partials/container.categories.ts @@ -13,7 +13,7 @@ export function categories( .forEach((category) => { md.push(heading(options.headingLevel, category.title)); if (category.description) { - md.push(this.partials.commentParts(category.description)); + md.push(this.helpers.getCommentParts(category.description)); } if (category.children) { md.push( diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/container.groups.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/container.groups.ts index a8f1867d..f1ec2f4d 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/partials/container.groups.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/partials/container.groups.ts @@ -26,7 +26,7 @@ export function groups( if (group.categories) { md.push(heading(options.headingLevel, getGroupTitle(group.title))); if (group.description) { - md.push(this.partials.commentParts(group.description)); + md.push(this.helpers.getCommentParts(group.description)); } md.push( this.partials.categories(group.categories, { @@ -44,7 +44,7 @@ export function groups( md.push(heading(options.headingLevel, getGroupTitle(group.title))); if (group.description) { - md.push(this.partials.commentParts(group.description)); + md.push(this.helpers.getCommentParts(group.description)); } if ( isPropertiesGroup && diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.reflectionIndex.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/member.reflectionIndex.ts index 74aba52b..edd53838 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.reflectionIndex.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/partials/member.reflectionIndex.ts @@ -17,7 +17,7 @@ export function reflectionIndex( model.categories.forEach((categoryGroup) => { md.push(heading(options.headingLevel, categoryGroup.title) + '\n'); if (categoryGroup.description) { - md.push(this.partials.commentParts(categoryGroup.description) + '\n'); + md.push(this.helpers.getCommentParts(categoryGroup.description) + '\n'); } md.push(this.helpers.getGroupIndex(categoryGroup) + '\n'); }); @@ -36,7 +36,7 @@ export function reflectionIndex( ); if (categoryGroup.description) { md.push( - this.partials.commentParts(categoryGroup.description) + '\n', + this.helpers.getCommentParts(categoryGroup.description) + '\n', ); } md.push(this.helpers.getGroupIndex(categoryGroup) + '\n'); 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 index 43ffdc5b..a1989b39 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signature.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signature.ts @@ -86,9 +86,9 @@ export function signature( this.partials.inheritance(model, { headingLevel: options.headingLevel }), ); - if (model.comment) { + if (modelComments) { md.push( - this.partials.comment(model.comment, { + this.partials.comment(modelComments, { headingLevel: options.headingLevel, showSummary: false, }), diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureReturns.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureReturns.ts index aaaef8f4..4daa3540 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureReturns.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureReturns.ts @@ -28,7 +28,7 @@ export function signatureReturns( if (model.comment?.blockTags.length) { const tags = model.comment.blockTags .filter((tag) => tag.tag === '@returns') - .map((tag) => this.partials.commentParts(tag.content)); + .map((tag) => this.helpers.getCommentParts(tag.content)); md.push(tags.join('\n\n')); } diff --git a/packages/typedoc-plugin-markdown/src/theme/context/resources.ts b/packages/typedoc-plugin-markdown/src/theme/context/resources.ts index cc53865d..c3d34d88 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/resources.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/resources.ts @@ -77,8 +77,6 @@ export const resourcePartials = (context: MarkdownThemeContext) => { isTableColumn?: boolean | undefined; } = {}, ) => partials.comment.apply(context, [model, options]) as string, - commentParts: (model: CommentDisplayPart[]) => - partials.commentParts.apply(context, [model]) as string, body: (model: ContainerReflection, options: { headingLevel: number }) => partials.body.apply(context, [model, options]) as string, categories: ( diff --git a/packages/typedoc-plugin-markdown/src/theme/context/templates/document.ts b/packages/typedoc-plugin-markdown/src/theme/context/templates/document.ts index e5b80977..5bd7015b 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/templates/document.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/templates/document.ts @@ -19,7 +19,7 @@ export function document( md.push(this.partials.breadcrumbs()); } - md.push(this.partials.commentParts(page.model.content)); + md.push(this.helpers.getCommentParts(page.model.content)); md.push(this.partials.footer()); diff --git a/packages/typedoc-plugin-markdown/src/theme/context/templates/project.ts b/packages/typedoc-plugin-markdown/src/theme/context/templates/project.ts index efa7b5f4..bce0fc70 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/templates/project.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/templates/project.ts @@ -21,7 +21,7 @@ export function project( this.page.project.url === this.page.url && this.options.getValue('entryPointStrategy') === EntryPointStrategy.Packages; - md.push(this.hook('index.page.begin').join('\n')); + md.push(this.hook('index.page.begin', this).join('\n')); if (!this.options.getValue('hidePageHeader')) { md.push(this.partials.header()); @@ -35,14 +35,14 @@ export function project( this.options.getValue('mergeReadme') && Boolean(page.model.readme); if (includeReadme && page.model.readme) { - md.push(this.partials.commentParts(page.model.readme)); + md.push(this.helpers.getCommentParts(page.model.readme)); } if (!this.options.getValue('hidePageTitle') && !includeReadme) { md.push(heading(1, this.partials.pageTitle())); } - md.push(this.hook('content.begin').join('\n')); + md.push(this.hook('content.begin', this).join('\n')); if (page.model.comment) { md.push(this.partials.comment(page.model.comment, { headingLevel: 2 })); @@ -72,7 +72,7 @@ export function project( md.push(this.partials.footer()); - md.push(this.hook('index.page.end').join('\n')); + md.push(this.hook('index.page.end', this).join('\n')); return md.join('\n\n'); } diff --git a/packages/typedoc-plugin-markdown/src/theme/context/templates/read-me.ts b/packages/typedoc-plugin-markdown/src/theme/context/templates/read-me.ts index 48451eb1..a1247eb6 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/templates/read-me.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/templates/read-me.ts @@ -21,7 +21,7 @@ export function readme( if (Boolean(page.model.readme)) { md.push( - this.partials.commentParts(page.model.readme as CommentDisplayPart[]), + this.helpers.getCommentParts(page.model.readme as CommentDisplayPart[]), ); } diff --git a/packages/typedoc-plugin-markdown/src/theme/context/templates/reflection.ts b/packages/typedoc-plugin-markdown/src/theme/context/templates/reflection.ts index ad5ac1fe..4f4965bd 100644 --- a/packages/typedoc-plugin-markdown/src/theme/context/templates/reflection.ts +++ b/packages/typedoc-plugin-markdown/src/theme/context/templates/reflection.ts @@ -12,7 +12,7 @@ export function reflection( ) { const md: string[] = []; - md.push(this.hook('page.begin').join('\n')); + md.push(this.hook('page.begin', this).join('\n')); if (!this.options.getValue('hidePageHeader')) { md.push(this.partials.header()); @@ -26,7 +26,7 @@ export function reflection( md.push(heading(1, this.partials.pageTitle())); } - md.push(this.hook('content.begin').join('\n')); + md.push(this.hook('content.begin', this).join('\n')); if ( [ @@ -44,7 +44,7 @@ export function reflection( md.push(this.partials.footer()); - md.push(this.hook('page.end').join('\n')); + md.push(this.hook('page.end', this).join('\n')); return md.join('\n\n'); } diff --git a/packages/typedoc-plugin-markdown/src/theme/markdown-themeContext.ts b/packages/typedoc-plugin-markdown/src/theme/markdown-themeContext.ts index e16090ed..789b33a6 100644 --- a/packages/typedoc-plugin-markdown/src/theme/markdown-themeContext.ts +++ b/packages/typedoc-plugin-markdown/src/theme/markdown-themeContext.ts @@ -5,11 +5,7 @@ import { resourcePartials, resourceTemplates, } from '@plugin/theme/context/resources'; -import { - MarkdownRenderer, - MarkdownRendererHooks, - PackageMetaData, -} from '@plugin/types'; +import { MarkdownRenderer, PackageMetaData } from '@plugin/types'; import * as path from 'path'; import { Internationalization, Options, Reflection } from 'typedoc'; @@ -161,6 +157,7 @@ export class MarkdownThemeContext { * * @internal */ - hook = (name: keyof MarkdownRendererHooks) => - (this.theme.owner as MarkdownRenderer).markdownHooks.emit(name, this); + hook: MarkdownRenderer['markdownHooks']['emit'] = (...params) => { + return (this.theme.owner as MarkdownRenderer).markdownHooks.emit(...params); + }; } diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/functions.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/functions.ts index 21ee5a95..c7232753 100644 --- a/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/functions.ts +++ b/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/functions.ts @@ -6,6 +6,8 @@ * This is a function that is assigned to a variable. * * @param someParam This is some numeric parameter. + * + * @see http://abc.com */ export const basicFunction = (someParam: number) => { return 0; diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.function.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.function.spec.ts.snap index 4503b7b3..a50ad0fa 100644 --- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.function.spec.ts.snap +++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.function.spec.ts.snap @@ -262,6 +262,10 @@ This is some numeric parameter. \`number\` +## See + +http://abc.com + ## Source [functions.ts:1](http://source-url) @@ -287,6 +291,10 @@ This is a function that is assigned to a variable. \`number\` +## See + +http://abc.com + ## Source [functions.ts:1](http://source-url)