diff --git a/devtools/examples/docusaurus/docusaurus.config.js b/devtools/examples/docusaurus/docusaurus.config.js index e38c39562..50bdd6998 100644 --- a/devtools/examples/docusaurus/docusaurus.config.js +++ b/devtools/examples/docusaurus/docusaurus.config.js @@ -63,7 +63,8 @@ const config = { expandObjects: true, readme: 'none', sidebar: { pretty: true }, - outputFileStrategy: 'modules', + outputFileStrategy: 'members', + propertiesFormat: 'htmlTable', cleanOutputDir: true, }, ], diff --git a/devtools/packages/fixtures/cli.ts b/devtools/packages/fixtures/cli.ts index 52867282a..0df47c2de 100755 --- a/devtools/packages/fixtures/cli.ts +++ b/devtools/packages/fixtures/cli.ts @@ -86,7 +86,6 @@ function writeMarkdown( path.join(__dirname, 'typedoc.cjs'), '-logLevel', 'Warn', - '-out', fullPath, ], diff --git a/devtools/packages/prebuild-options/tasks/generate-docs.ts b/devtools/packages/prebuild-options/tasks/generate-docs.ts index d77a30e46..5146983f0 100644 --- a/devtools/packages/prebuild-options/tasks/generate-docs.ts +++ b/devtools/packages/prebuild-options/tasks/generate-docs.ts @@ -135,6 +135,7 @@ ${presetsJson} meta.push(type); } if ( + option.type !== ParameterType.Flags && option.type !== ParameterType.Array && option.type !== ParameterType.Mixed ) { diff --git a/docs/pages/docs/options.mdx b/docs/pages/docs/options.mdx index 7934fde23..b4111226d 100644 --- a/docs/pages/docs/options.mdx +++ b/docs/pages/docs/options.mdx @@ -395,7 +395,7 @@ This option should be set when a full type representation is preferred. Specify the render style of parameter and type parameter groups. -> Accepts either `"list"` or `"table"`. Defaults to `"list"`. +> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. This option either renders parameters for functions and class methods as a list or in tabular format. @@ -413,7 +413,7 @@ This option either renders parameters for functions and class methods as a list Specify the render style of property groups for interfaces and classes. -> Accepts either `"list"` or `"table"`. Defaults to `"list"`. +> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. This option either renders properties for classes and interfaces as a list or in tabular format. @@ -429,7 +429,7 @@ This option either renders properties for classes and interfaces as a list or in Specify the render style of enumeration members. -> Accepts either `"list"` or `"table"`. Defaults to `"list"`. +> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. This option either renders members of enums as a list or in tabular format. @@ -447,7 +447,7 @@ This option either renders members of enums as a list or in tabular format. Specify the render style for type declaration members. -> Accepts either `"list"` or `"table"`. Defaults to `"list"`. +> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. This option either renders type declarations as a list or in tabular format. @@ -463,7 +463,7 @@ This option either renders type declarations as a list or in tabular format. Specify the render format for index items. -> Accepts either `"list"` or `"table"`. Defaults to `"list"`. +> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. This option renders index items either as a simple list or in a table with a description column exposing the comment summary. @@ -477,6 +477,33 @@ For a packages index page (when `--entryPointStrategy` equals `packages`), the p --- +### tableColumns + + + Control header alignment and column visibility in tables. + + +> + +By default, all available data for symbols are displayed in columns, which can result in very large tables. + +This option allows you to control the visibility of columns, prioritizing readability over displaying complete data. + +```json filename="typedoc.json" +{ + "tableColumns": { + "excludeDefaultsCol": false, + "excludeInheritedFromCol": false, + "excludeModifiersCol": false, + "excludeOverridesCol": false, + "excludeSourcesCol": false, + "leftAlignHeadings": false + } +} +``` + +--- + ### textContentMappings @@ -693,7 +720,7 @@ This option can be used for engines that require the preservation of anchor link Configures how the navigation model will be generated. -> Defaults to `{"excludeGroups":false,"excludeCategories":false,"excludeFolders":false}`. +> By default navigation is not written to file but can be consumed programmatically. Please see [Navigation Guide](/docs/navigation) for more information. diff --git a/packages/typedoc-plugin-markdown/src/libs/markdown/html-table.ts b/packages/typedoc-plugin-markdown/src/libs/markdown/html-table.ts new file mode 100644 index 000000000..73ba8df79 --- /dev/null +++ b/packages/typedoc-plugin-markdown/src/libs/markdown/html-table.ts @@ -0,0 +1,26 @@ +export function htmlTable( + headers: string[], + rows: string[][], + leftAlignHeadings = false, +) { + return ` +${headers.map((header) => `${header}`).join('')}${rows + .map( + (row) => + ` +${row + .map( + (cell) => + ` +`, + ) + .join('')} +`, + ) + .join('')} +
+ +${cell === '-' ? '‐' : cell} + +
`; +} diff --git a/packages/typedoc-plugin-markdown/src/libs/markdown/index.ts b/packages/typedoc-plugin-markdown/src/libs/markdown/index.ts index a9c65b683..bbc5647fd 100644 --- a/packages/typedoc-plugin-markdown/src/libs/markdown/index.ts +++ b/packages/typedoc-plugin-markdown/src/libs/markdown/index.ts @@ -10,6 +10,7 @@ export { bold } from './bold'; export { codeBlock } from './code-block'; export { heading } from './heading'; export { horizontalRule } from './horizontal-rule'; +export { htmlTable } from './html-table'; export { indentBlock } from './indent-block'; export { italic } from './italic'; export { link } from './link'; diff --git a/packages/typedoc-plugin-markdown/src/libs/markdown/table.ts b/packages/typedoc-plugin-markdown/src/libs/markdown/table.ts index a819fe357..e10a76fbb 100644 --- a/packages/typedoc-plugin-markdown/src/libs/markdown/table.ts +++ b/packages/typedoc-plugin-markdown/src/libs/markdown/table.ts @@ -1,10 +1,17 @@ +import { formatTableCell } from '../utils/format-table-cell'; /** * Comments for table * @param headers * @param rows */ -export function table(headers: string[], rows: string[][]) { +export function table( + headers: string[], + rows: string[][], + headerLeftAlign = false, +) { return `\n| ${headers.join(' | ')} |\n| ${headers - .map(() => ':------') - .join(' | ')} |\n${rows.map((row) => `| ${row.join(' | ')} |\n`).join('')}`; + .map(() => `${headerLeftAlign ? ':' : ''}------`) + .join( + ' | ', + )} |\n${rows.map((row) => `| ${row.map((cell) => formatTableCell(cell)).join(' | ')} |\n`).join('')}`; } diff --git a/packages/typedoc-plugin-markdown/src/libs/utils/format-markdown.spec.ts b/packages/typedoc-plugin-markdown/src/libs/utils/format-markdown.spec.ts deleted file mode 100644 index 51cad8707..000000000 --- a/packages/typedoc-plugin-markdown/src/libs/utils/format-markdown.spec.ts +++ /dev/null @@ -1,26 +0,0 @@ -import { formatMarkdown } from './format-markdown'; - -describe('formatMarkdown', () => { - it('should trim content and restrict new lines', () => { - const input = ` - -# headline - - -Paragraph - - - -## headline - - `; - const expectedOutput = `# headline - -Paragraph - -## headline -`; - const result = formatMarkdown(input); - expect(result).toEqual(expectedOutput); - }); -}); diff --git a/packages/typedoc-plugin-markdown/src/libs/utils/format-table-cell.spec.ts b/packages/typedoc-plugin-markdown/src/libs/utils/format-table-cell.spec.ts new file mode 100644 index 000000000..c4fbb4f5f --- /dev/null +++ b/packages/typedoc-plugin-markdown/src/libs/utils/format-table-cell.spec.ts @@ -0,0 +1,16 @@ +import { formatTableCell } from './format-table-cell'; + +describe('formatTableCell', () => { + it('should correctly format the cell content', () => { + const input = ` + This is a test + \`\`\`ts + const x = 10; + \`\`\` + with multiple spaces. + `; + const expectedOutput = + 'This is a test `const x = 10;` with multiple spaces.'; + expect(formatTableCell(input)).toBe(expectedOutput); + }); +}); diff --git a/packages/typedoc-plugin-markdown/src/libs/utils/format-table-cell.ts b/packages/typedoc-plugin-markdown/src/libs/utils/format-table-cell.ts new file mode 100644 index 000000000..77cdf92b2 --- /dev/null +++ b/packages/typedoc-plugin-markdown/src/libs/utils/format-table-cell.ts @@ -0,0 +1,15 @@ +/** + * - Replace new lines with spaces + * - Replaces code blocks with single backticks + * - Replaces multiple spaces with single spaces + */ +export function formatTableCell(str: string) { + return str + .replace(/\n/g, ' ') + .replace( + /```(\w+\s)?([\s\S]*?)```/gs, + (match, p1, p2) => `\`${p2.trim()}\``, + ) + .replace(/ +/g, ' ') + .trim(); +} diff --git a/packages/typedoc-plugin-markdown/src/libs/utils/format-table-column.spec.ts b/packages/typedoc-plugin-markdown/src/libs/utils/format-table-column.spec.ts deleted file mode 100644 index 0e11e7469..000000000 --- a/packages/typedoc-plugin-markdown/src/libs/utils/format-table-column.spec.ts +++ /dev/null @@ -1,16 +0,0 @@ -import { formatTableColumn } from './format-table-column'; - -describe('formatTableColumn', () => { - it('should correctly escape pipes', () => { - const input = 'This is a test | with a pipe.'; - const expectedOutput = 'This is a test \\| with a pipe.'; - expect(formatTableColumn(input)).toBe(expectedOutput); - }); - - it('should correctly convert multi-line markdown to HTML', () => { - const input = `1. First item -2. Second item`; - const expectedOutput = '
  1. First item
  2. Second item
'; - expect(formatTableColumn(input)).toBe(expectedOutput); - }); -}); diff --git a/packages/typedoc-plugin-markdown/src/libs/utils/format-table-column.ts b/packages/typedoc-plugin-markdown/src/libs/utils/format-table-column.ts deleted file mode 100644 index 47b966abf..000000000 --- a/packages/typedoc-plugin-markdown/src/libs/utils/format-table-column.ts +++ /dev/null @@ -1,13 +0,0 @@ -import { markdownBlocksToHtml } from './markdown-blocks-to-html'; -import { normalizeLineBreaks } from './normalize-line-breaks'; - -export function formatTableColumn(str: string) { - // Normalize line breaks - let md = normalizeLineBreaks(str); - // If comments are on multiple lines convert markdown block tags to HTML and remove new lines. - if (md.split('\n').length > 1) { - md = markdownBlocksToHtml(md); - } - // Finally return with escaped pipes - return md.replace(/\|/g, '\\|'); -} diff --git a/packages/typedoc-plugin-markdown/src/libs/utils/index.ts b/packages/typedoc-plugin-markdown/src/libs/utils/index.ts index 52eeeb97b..b263c8310 100644 --- a/packages/typedoc-plugin-markdown/src/libs/utils/index.ts +++ b/packages/typedoc-plugin-markdown/src/libs/utils/index.ts @@ -5,10 +5,9 @@ export { camelToTitleCase } from './camel-to-title-case'; export { escapeChars } from './escape-chars'; export { formatMarkdown } from './format-markdown'; -export { formatTableColumn } from './format-table-column'; +export { formatTableCell } from './format-table-cell'; export { getFileNameWithExtension } from './get-file-name-with-extension'; export { isQuoted } from './is-quoted'; -export { markdownBlocksToHtml } from './markdown-blocks-to-html'; export { normalizeLineBreaks } from './normalize-line-breaks'; export { removeFirstScopedDirectory } from './remove-first-scoped-directory'; export { removeLineBreaks } from './remove-line-breaks'; diff --git a/packages/typedoc-plugin-markdown/src/libs/utils/markdown-blocks-to-html.spec.ts b/packages/typedoc-plugin-markdown/src/libs/utils/markdown-blocks-to-html.spec.ts deleted file mode 100644 index df1a1651b..000000000 --- a/packages/typedoc-plugin-markdown/src/libs/utils/markdown-blocks-to-html.spec.ts +++ /dev/null @@ -1,35 +0,0 @@ -import { markdownBlocksToHtml } from './markdown-blocks-to-html'; - -describe('markdownBlocksToHtml', () => { - it('should correctly convert markdown to HTML', () => { - const input = `This is a test - -Double new line - -### Heading - -

Subheading

- -- list item 1 -- list item 2`; - - const expectedOutput = `

This is a test

Double new line

Heading

Subheading

`; - - expect(markdownBlocksToHtml(input)).toBe(expectedOutput); - }); - - it('should correctly convert markdown to HTML', () => { - const input = `

paragraph

- -New line - -

paragraph

-

- paragraph with new line -

`; - - const expectedOutput = `

paragraph

New line

paragraph

paragraph with new line

`; - - expect(markdownBlocksToHtml(input)).toBe(expectedOutput); - }); -}); diff --git a/packages/typedoc-plugin-markdown/src/libs/utils/markdown-blocks-to-html.ts b/packages/typedoc-plugin-markdown/src/libs/utils/markdown-blocks-to-html.ts deleted file mode 100644 index 8a5309e7c..000000000 --- a/packages/typedoc-plugin-markdown/src/libs/utils/markdown-blocks-to-html.ts +++ /dev/null @@ -1,73 +0,0 @@ -export function markdownBlocksToHtml(markdownText: string) { - // Remove new lines inside

tags - markdownText = markdownText.replace(/

([\s\S]*?)<\/p>/gm, (match, p1) => { - const contentWithoutNewLinesOrLeadingSpaces = p1 - .replace(/\r?\n|\r/g, ' ') - .replace(/^\s+/, ''); - return `

${contentWithoutNewLinesOrLeadingSpaces}

`; - }); - - // Replace headers - markdownText = markdownText.replace( - /^(#{1,6})\s*(.*?)\s*$/gm, - (match, p1, p2) => { - const level = p1.length; - return `${p2}`; - }, - ); - - // Replace triple code blocks with code - markdownText = markdownText.replace( - /```.*?\n([\s\S]*?)```/gs, - '$1', - ); - - // Replace horizontal rules - markdownText = markdownText.replace(/^[-*_]{3,}\s*$/gm, '
'); - - // Replace unordered lists - markdownText = markdownText.replace(/^(\s*-\s+.+$(\r?\n)?)+/gm, (match) => { - const items = match.trim().split('\n'); - const listItems = items - .map((item) => `
  • ${item.trim().substring(2)}
  • `) - .join(''); - return ``; - }); - - // Replace ordered lists - markdownText = markdownText.replace( - /^(\s*\d+\.\s+.+$(\r?\n)?)+/gm, - (match) => { - const items = match.trim().split('\n'); - const listItems = items - .map( - (item) => `
  • ${item.trim().substring(item.indexOf('.') + 2)}
  • `, - ) - .join(''); - return `
      ${listItems}
    `; - }, - ); - - // Replace paragraphs - markdownText = markdownText.replace( - /^(?!.*<[^>]+>)(.+?)(?:(?:\r\n|\r|\n){2,}|$)(?!.*<[^>]+>)/gm, - '

    $1

    ', - ); - - // Replace ordered lists - markdownText = markdownText.replace( - /^(\s*\d+\.\s+.+$(\r?\n)?)+/gm, - (match) => { - const items = match.trim().split('\n'); - const listItems = items - .map( - (item) => `
  • ${item.trim().substring(item.indexOf('.') + 1)}
  • `, - ) - .join(''); - return `
      ${listItems}
    `; - }, - ); - - // Finally remove all new lines - return markdownText.replace(/\n/g, ''); -} diff --git a/packages/typedoc-plugin-markdown/src/options/declarations.ts b/packages/typedoc-plugin-markdown/src/options/declarations.ts index cc6ac16a7..1c4b05b52 100644 --- a/packages/typedoc-plugin-markdown/src/options/declarations.ts +++ b/packages/typedoc-plugin-markdown/src/options/declarations.ts @@ -384,6 +384,26 @@ export const indexFormat: Partial = { defaultValue: FormatStyle.List, }; +/** + * By default, all available data for symbols are displayed in columns, which can result in very large tables. + * + * This option allows you to control the visibility of columns, prioritizing readability over displaying complete data. + * + * @category UX + */ +export const tableColumns: Partial = { + help: 'Control header alignment and column visibility in tables.', + type: ParameterType.Flags, + defaults: { + excludeDefaultsCol: false, + excludeInheritedFromCol: false, + excludeModifiersCol: false, + excludeOverridesCol: false, + excludeSourcesCol: false, + leftAlignHeadings: false, + }, +}; + /** * * **Please note TypeDoc 0.26 will be introducing a native i18n implementation. This option will likely be deprecated in favour of utilizing the native implementation when 0.26 is released.** diff --git a/packages/typedoc-plugin-markdown/src/options/option-maps.ts b/packages/typedoc-plugin-markdown/src/options/option-maps.ts index cb85b35fa..f68976c3f 100644 --- a/packages/typedoc-plugin-markdown/src/options/option-maps.ts +++ b/packages/typedoc-plugin-markdown/src/options/option-maps.ts @@ -11,6 +11,7 @@ export type OutputFileStrategy = export const FormatStyle = { List: 'list', Table: 'table', + HtmlTable: 'htmlTable', } as const; export type FormatStyle = (typeof FormatStyle)[keyof typeof FormatStyle]; diff --git a/packages/typedoc-plugin-markdown/src/options/option-types.ts b/packages/typedoc-plugin-markdown/src/options/option-types.ts index 340617d07..90a10054f 100644 --- a/packages/typedoc-plugin-markdown/src/options/option-types.ts +++ b/packages/typedoc-plugin-markdown/src/options/option-types.ts @@ -7,7 +7,7 @@ declare module 'typedoc' { anchorPrefix: string; entryFileName: string; entryModule: string; - enumMembersFormat: 'list' | 'table'; + enumMembersFormat: 'list' | 'table' | 'htmlTable'; excludeGroups: boolean; excludeScopesInPaths: boolean; expandObjects: boolean; @@ -17,7 +17,7 @@ declare module 'typedoc' { hideBreadcrumbs: boolean; hidePageHeader: boolean; hidePageTitle: boolean; - indexFormat: 'list' | 'table'; + indexFormat: 'list' | 'table' | 'htmlTable'; membersWithOwnFile: ( | 'Enum' | 'Variable' @@ -33,13 +33,21 @@ declare module 'typedoc' { excludeFolders: boolean; }; outputFileStrategy: 'members' | 'modules'; - parametersFormat: 'list' | 'table'; + parametersFormat: 'list' | 'table' | 'htmlTable'; preserveAnchorCasing: boolean; - propertiesFormat: 'list' | 'table'; + propertiesFormat: 'list' | 'table' | 'htmlTable'; publicPath: string; sanitizeComments: boolean; + tableColumns: { + excludeDefaultsCol: boolean; + excludeInheritedFromCol: boolean; + excludeModifiersCol: boolean; + excludeOverridesCol: boolean; + excludeSourcesCol: boolean; + leftAlignHeadings: boolean; + }; textContentMappings: ManuallyValidatedOption>; - typeDeclarationFormat: 'list' | 'table'; + typeDeclarationFormat: 'list' | 'table' | 'htmlTable'; useCodeBlocks: boolean; useHTMLAnchors: boolean; } @@ -69,7 +77,7 @@ export interface PluginOptions { /** * Specify the render style of enumeration members. */ - enumMembersFormat: 'list' | 'table'; + enumMembersFormat: 'list' | 'table' | 'htmlTable'; /** * Excludes grouping by kind so all members are rendered and sorted at the same level. @@ -119,7 +127,7 @@ export interface PluginOptions { /** * Specify the render format for index items. */ - indexFormat: 'list' | 'table'; + indexFormat: 'list' | 'table' | 'htmlTable'; /** * Determines which members are exported to their own file when `outputFileStrategy` equals `members`. @@ -155,7 +163,7 @@ export interface PluginOptions { /** * Specify the render style of parameter and type parameter groups. */ - parametersFormat: 'list' | 'table'; + parametersFormat: 'list' | 'table' | 'htmlTable'; /** * Preserve anchor casing when generating link to symbols. @@ -165,7 +173,7 @@ export interface PluginOptions { /** * Specify the render style of property groups for interfaces and classes. */ - propertiesFormat: 'list' | 'table'; + propertiesFormat: 'list' | 'table' | 'htmlTable'; /** * Specify the base path for all urls. @@ -177,6 +185,18 @@ export interface PluginOptions { */ sanitizeComments: boolean; + /** + * Control header alignment and column visibility in tables. + */ + tableColumns: { + excludeDefaultsCol: boolean; + excludeInheritedFromCol: boolean; + excludeModifiersCol: boolean; + excludeOverridesCol: boolean; + excludeSourcesCol: boolean; + leftAlignHeadings: boolean; + }; + /** * Provides a mechanism to change the content of text used in documentation. */ @@ -185,7 +205,7 @@ export interface PluginOptions { /** * Specify the render style for type declaration members. */ - typeDeclarationFormat: 'list' | 'table'; + typeDeclarationFormat: 'list' | 'table' | 'htmlTable'; /** * Wraps signatures and declarations in code blocks. 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 1ae04a6a7..e39846c92 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 @@ -1,5 +1,5 @@ import { bold, heading } from '@plugin/libs/markdown'; -import { camelToTitleCase, formatTableColumn } from '@plugin/libs/utils'; +import { camelToTitleCase } from '@plugin/libs/utils'; import { sanitizeComments } from '@plugin/libs/utils/sanitize-comments'; import { MarkdownThemeContext } from '@plugin/theme'; import { Comment, CommentTag } from 'typedoc'; @@ -84,5 +84,5 @@ export function comment( ? sanitizeComments(output) : output; - return opts.isTableColumn ? formatTableColumn(parsedOutput) : parsedOutput; + return parsedOutput; } diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/container.groups.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/container.groups.ts index 76bc7d7df..186086cc0 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/container.groups.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/container.groups.ts @@ -51,7 +51,10 @@ export function groups( } if ( isPropertiesGroup && - this.options.getValue('propertiesFormat') === 'table' + this.options + .getValue('propertiesFormat') + .toLowerCase() + .includes('table') ) { md.push( this.partials.declarationsTable(group.children, { @@ -61,7 +64,10 @@ export function groups( ); } else if ( isEnumGroup && - this.options.getValue('enumMembersFormat') === 'table' + this.options + .getValue('enumMembersFormat') + .toLowerCase() + .includes('table') ) { md.push(this.partials.enumMembersTable(group.children)); } else { diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.accessor.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.accessor.ts index 7c4ba2bcc..b62bbe229 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.accessor.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.accessor.ts @@ -47,7 +47,9 @@ export function accessor( md.push( heading(options.headingLevel, this.getText('kind.parameter.plural')), ); - if (this.options.getValue('parametersFormat') === 'table') { + if ( + this.options.getValue('parametersFormat').toLowerCase().includes('table') + ) { md.push(this.partials.parametersTable(model.setSignature.parameters)); } else { md.push(this.partials.parametersList(model.setSignature.parameters)); diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.declaration.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.declaration.ts index c1123f2db..f49d51961 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.declaration.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.declaration.ts @@ -94,7 +94,9 @@ export function declaration( md.push( heading(opts.headingLevel, this.getText('kind.typeParameter.plural')), ); - if (this.options.getValue('parametersFormat') === 'table') { + if ( + this.options.getValue('parametersFormat').toLowerCase().includes('table') + ) { md.push(this.partials.typeParametersTable(model.typeParameters)); } else { md.push(this.partials.typeParametersList(model.typeParameters)); diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.enumMembersTable.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.enumMembersTable.ts index ec4892783..debd2ddb7 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.enumMembersTable.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.enumMembersTable.ts @@ -1,4 +1,4 @@ -import { backTicks } from '@plugin/libs/markdown'; +import { backTicks, htmlTable, table } from '@plugin/libs/markdown'; import { removeLineBreaks } from '@plugin/libs/utils'; import { MarkdownThemeContext } from '@plugin/theme'; import { DeclarationReflection, ReflectionType } from 'typedoc'; @@ -12,6 +12,8 @@ export function enumMembersTable( this: MarkdownThemeContext, model: DeclarationReflection[], ): string { + const tableColumnsOptions = this.options.getValue('tableColumns'); + const comments = model.map((param) => !!param.comment?.hasVisibleComponent()); const hasComments = comments.some((value) => Boolean(value)); @@ -24,7 +26,9 @@ export function enumMembersTable( headers.push(this.getText('label.description')); } - const rows = model.map((property: DeclarationReflection) => { + const rows: string[][] = []; + + model.forEach((property: DeclarationReflection) => { const propertyType = this.helpers.getDeclarationType(property); const row: string[] = []; const nameColumn: string[] = []; @@ -38,9 +42,11 @@ export function enumMembersTable( nameColumn.push(backTicks(property.name)); row.push(nameColumn.join(' ')); + if (propertyType) { row.push(removeLineBreaks(this.partials.someType(propertyType))); } + if (hasComments) { const comments = getComments(property); if (comments) { @@ -49,15 +55,12 @@ export function enumMembersTable( row.push('-'); } } - - return `| ${row.join(' | ')} |\n`; + rows.push(row); }); - const output = `\n| ${headers.join(' | ')} |\n| ${headers - .map(() => ':------') - .join(' | ')} |\n${rows.join('')}`; - - return output; + return this.options.getValue('enumMembersFormat') == 'table' + ? table(headers, rows, tableColumnsOptions.leftAlignHeadings) + : htmlTable(headers, rows, tableColumnsOptions.leftAlignHeadings); } function getComments(property: DeclarationReflection) { diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.memberWithGroups.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.memberWithGroups.ts index ccff019e7..ccfa3a350 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.memberWithGroups.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.memberWithGroups.ts @@ -34,7 +34,9 @@ export function memberWithGroups( md.push( heading(options.headingLevel, this.getText('kind.typeParameter.plural')), ); - if (this.options.getValue('parametersFormat') === 'table') { + if ( + this.options.getValue('parametersFormat').toLowerCase().includes('table') + ) { md.push(this.partials.typeParametersTable(model.typeParameters)); } else { md.push(this.partials.typeParametersList(model.typeParameters)); diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.parametersTable.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.parametersTable.ts index 35bc81497..4e3c67884 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.parametersTable.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.parametersTable.ts @@ -1,4 +1,4 @@ -import { backTicks, table } from '@plugin/libs/markdown'; +import { backTicks, htmlTable, table } from '@plugin/libs/markdown'; import { removeLineBreaks } from '@plugin/libs/utils'; import { MarkdownThemeContext } from '@plugin/theme'; import { ParameterReflection, ReflectionKind, ReflectionType } from 'typedoc'; @@ -10,6 +10,8 @@ export function parametersTable( this: MarkdownThemeContext, model: ParameterReflection[], ): string { + const tableColumnsOptions = this.options.getValue('tableColumns'); + const parseParams = (current: any, acc: any) => { const shouldFlatten = current.type?.declaration?.kind === ReflectionKind.TypeLiteral && @@ -32,7 +34,8 @@ export function parametersTable( ); }; - const showDefaults = hasDefaultValues(model); + const showDefaults = + !tableColumnsOptions.excludeDefaultsCol && hasDefaultValues(model); const parsedParams = model.reduce( (acc: any, current: any) => parseParams(current, acc), @@ -99,7 +102,9 @@ export function parametersTable( rows.push(row); }); - return table(headers, rows); + return this.options.getValue('parametersFormat') == 'table' + ? table(headers, rows, tableColumnsOptions.leftAlignHeadings) + : htmlTable(headers, rows, tableColumnsOptions.leftAlignHeadings); } function hasDefaultValues(parameters: ParameterReflection[]) { diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.propertiesTable.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.propertiesTable.ts index 68f8ae663..789221769 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.propertiesTable.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.propertiesTable.ts @@ -1,5 +1,10 @@ -import { backTicks, strikeThrough, table } from '@plugin/libs/markdown'; -import { formatTableColumn, removeLineBreaks } from '@plugin/libs/utils'; +import { + backTicks, + htmlTable, + strikeThrough, + table, +} from '@plugin/libs/markdown'; +import { removeLineBreaks } from '@plugin/libs/utils'; import { MarkdownThemeContext } from '@plugin/theme'; import { DeclarationReflection } from 'typedoc'; import { getPropertyDefaultValue } from '../helpers/get-property-default-value'; @@ -17,14 +22,26 @@ export function declarationsTable( model: DeclarationReflection[], options?: { isEventProps: boolean }, ): string { + const tableColumnsOptions = this.options.getValue('tableColumns'); const modifiers = model.map((param) => this.helpers.getModifier(param)?.toString(), ); - const hasModifiers = modifiers.some((value) => Boolean(value)); + + const hasModifiers = + !tableColumnsOptions.excludeModifiersCol && + modifiers.some((value) => Boolean(value)); + const flags = model.map((param) => this.partials.reflectionFlags(param)); const hasFlags = flags.some((value) => Boolean(value)); - const hasOverrides = model.some((prop) => Boolean(prop.overwrites)); - const hasInheritance = model.some((prop) => Boolean(prop.inheritedFrom)); + + const hasOverrides = + !tableColumnsOptions.excludeOverridesCol && + model.some((prop) => Boolean(prop.overwrites)); + + const hasInheritance = + !tableColumnsOptions.excludeInheritedFromCol && + model.some((prop) => Boolean(prop.inheritedFrom)); + const hasDefaults = model.some((prop) => Boolean(getPropertyDefaultValue(prop)), ); @@ -32,6 +49,10 @@ export function declarationsTable( (prop) => prop.comment?.blockTags?.length || prop?.comment?.summary?.length, ); + const hasSources = + !tableColumnsOptions.excludeSourcesCol && + !this.options.getValue('disableSources'); + const headers: string[] = []; headers.push( @@ -66,6 +87,10 @@ export function declarationsTable( headers.push(this.getText('label.inheritedFrom')); } + if (hasSources) { + headers.push(this.getText('label.source')); + } + const rows: string[][] = []; const declarations = this.helpers.getFlattenedDeclarations(model); @@ -113,11 +138,7 @@ export function declarationsTable( } if (hasDefaults) { - row.push( - formatTableColumn( - getPropertyDefaultValue(property) || backTicks('undefined'), - ), - ); + row.push(getPropertyDefaultValue(property) || backTicks('undefined')); } if (hasComments) { @@ -134,18 +155,28 @@ export function declarationsTable( if (hasOverrides) { row.push( - this.partials.inheritance(property, { headingLevel: -1 }) || '-', + property.overwrites + ? this.partials.inheritance(property, { headingLevel: -1 }) + : '-', ); } if (hasInheritance) { row.push( - this.partials.inheritance(property, { headingLevel: -1 }) || '-', + property.inheritedFrom + ? this.partials.inheritance(property, { headingLevel: -1 }) + : '-', ); } + if (hasSources) { + row.push(this.partials.sources(property, { headingLevel: -1 })); + } + rows.push(row); }); - return table(headers, rows); + return this.options.getValue('propertiesFormat') == 'table' + ? table(headers, rows, tableColumnsOptions.leftAlignHeadings) + : htmlTable(headers, rows, tableColumnsOptions.leftAlignHeadings); } diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.reflectionIndex.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.reflectionIndex.ts index 9e62c1620..f205eba41 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.reflectionIndex.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.reflectionIndex.ts @@ -89,6 +89,8 @@ function getTable( context: MarkdownThemeContext, children: DeclarationReflection[], ) { + const tableColumnsOptions = context.options.getValue('tableColumns'); + const headers = [ context.options.getValue('excludeGroups') ? context.getText('label.member') @@ -121,7 +123,7 @@ function getTable( } rows.push(row); }); - return table(headers, rows); + return table(headers, rows, tableColumnsOptions.leftAlignHeadings); } function getList( diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.signature.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.signature.ts index ddf2d73b6..0164bb201 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.signature.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.signature.ts @@ -44,7 +44,9 @@ export function signature( md.push( heading(options.headingLevel, this.getText('kind.typeParameter.plural')), ); - if (this.options.getValue('parametersFormat') === 'table') { + if ( + this.options.getValue('parametersFormat').toLowerCase().includes('table') + ) { md.push(this.partials.typeParametersTable(model.typeParameters)); } else { md.push(this.partials.typeParametersList(model.typeParameters)); @@ -55,7 +57,9 @@ export function signature( md.push( heading(options.headingLevel, this.getText('kind.parameter.plural')), ); - if (this.options.getValue('parametersFormat') === 'table') { + if ( + this.options.getValue('parametersFormat').toLowerCase().includes('table') + ) { md.push(this.partials.parametersTable(model.parameters)); } else { md.push(this.partials.parametersList(model.parameters)); diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeDeclaration.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeDeclaration.ts index 0f756e253..16648be68 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeDeclaration.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeDeclaration.ts @@ -11,7 +11,12 @@ export function typeDeclaration( ): string { const md: string[] = []; - if (this.options.getValue('typeDeclarationFormat') === 'table') { + if ( + this.options + .getValue('typeDeclarationFormat') + .toLowerCase() + .includes('table') + ) { md.push(this.partials.typeDeclarationTable(model)); } else { md.push(this.partials.typeDeclarationList(model, options.headingLevel)); diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeDeclarationTable.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeDeclarationTable.ts index a28e1e4ff..9c374dfed 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeDeclarationTable.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeDeclarationTable.ts @@ -1,4 +1,4 @@ -import { backTicks, table } from '@plugin/libs/markdown'; +import { backTicks, htmlTable, table } from '@plugin/libs/markdown'; import { escapeChars } from '@plugin/libs/utils'; import { MarkdownThemeContext } from '@plugin/theme'; import { DeclarationReflection } from 'typedoc'; @@ -10,6 +10,8 @@ export function typeDeclarationTable( this: MarkdownThemeContext, model: DeclarationReflection[], ): string { + const tableColumnsOptions = this.options.getValue('tableColumns'); + const headers: string[] = []; const declarations = this.helpers.getFlattenedDeclarations(model, { @@ -64,5 +66,7 @@ export function typeDeclarationTable( rows.push(row); }); - return table(headers, rows); + return this.options.getValue('typeDeclarationFormat') == 'table' + ? table(headers, rows, tableColumnsOptions.leftAlignHeadings) + : htmlTable(headers, rows, tableColumnsOptions.leftAlignHeadings); } diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeParametersTable.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeParametersTable.ts index 3d5e4a07b..65a71eb75 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeParametersTable.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeParametersTable.ts @@ -1,4 +1,4 @@ -import { backTicks, italic, table } from '@plugin/libs/markdown'; +import { backTicks, htmlTable, italic, table } from '@plugin/libs/markdown'; import { MarkdownThemeContext } from '@plugin/theme'; import { TypeParameterReflection } from 'typedoc'; @@ -9,9 +9,11 @@ export function typeParametersTable( this: MarkdownThemeContext, model: TypeParameterReflection[], ): string { - const hasDefault = model.some((typeParameter) => - Boolean(typeParameter.default), - ); + const tableColumnsOptions = this.options.getValue('tableColumns'); + + const hasDefault = + !tableColumnsOptions.excludeDefaultsCol && + model.some((typeParameter) => Boolean(typeParameter.default)); const hasComments = model.some((typeParameter) => Boolean(typeParameter.comment), @@ -65,5 +67,7 @@ export function typeParametersTable( rows.push(row); }); - return table(headers, rows); + return this.options.getValue('parametersFormat') == 'table' + ? table(headers, rows, tableColumnsOptions.leftAlignHeadings) + : htmlTable(headers, rows, tableColumnsOptions.leftAlignHeadings); } diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.packagesIndex.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.packagesIndex.ts index 995be7787..16d6079a4 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.packagesIndex.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.packagesIndex.ts @@ -11,6 +11,8 @@ export function packagesIndex( this: MarkdownThemeContext, model: ProjectReflection, ): string { + const tableColumnsOptions = this.options.getValue('tableColumns'); + const md: string[] = []; md.push(heading(2, this.getText('label.packages'))); @@ -52,7 +54,9 @@ export function packagesIndex( return rows; }); - md.push(table(headers, packageRows || [])); + md.push( + table(headers, packageRows || [], tableColumnsOptions.leftAlignHeadings), + ); } else { const packagesList = model.children?.map((projectPackage) => { const urlTo = Boolean(projectPackage.readme) diff --git a/packages/typedoc-plugin-markdown/test/fixtures/config.ts b/packages/typedoc-plugin-markdown/test/fixtures/config.ts index ac2159da6..27dd94bdb 100644 --- a/packages/typedoc-plugin-markdown/test/fixtures/config.ts +++ b/packages/typedoc-plugin-markdown/test/fixtures/config.ts @@ -12,6 +12,10 @@ const config: Record = { ], hidePageHeader: true, hideBreadcrumbs: true, + tableColumns: { + excludeSourcesCol: true, + leftAlignHeadings: true, + }, }, options: [ {}, @@ -39,6 +43,9 @@ const config: Record = { disableSources: true, expandObjects: true, expandParameters: true, + tableColumns: { + leftAlignHeadings: true, + }, }, options: [ {}, @@ -86,6 +93,9 @@ const config: Record = { theme: 'stub-groups', disableSources: true, entryFileName: 'index.md', + tableColumns: { + leftAlignHeadings: true, + }, }, options: [ { @@ -115,24 +125,38 @@ const config: Record = { entryPoints: '/comments/index.ts', commonOptions: { plugin: [path.join(__dirname, 'custom-plugins', 'navigation-plugin.mjs')], - disableSources: true, hidePageHeader: true, hideBreadcrumbs: true, - enumMembersFormat: 'table', - propertiesFormat: 'table', readme: 'none', + disableSources: true, media: './test/fixtures/media', includes: './test/fixtures/inc', }, options: [ - {}, + { + enumMembersFormat: 'table', + parametersFormat: 'table', + propertiesFormat: 'table', + typeDeclarationFormat: 'table', + }, { useHTMLAnchors: true, preserveAnchorCasing: true, publicPath: 'http://example.com', - fileExtension: '.mdx', sanitizeComments: true, flattenOutputFiles: true, + enumMembersFormat: 'htmlTable', + parametersFormat: 'htmlTable', + propertiesFormat: 'htmlTable', + typeDeclarationFormat: 'htmlTable', + tableColumns: { + excludeDefaultsCol: true, + excludeInheritedFromCol: true, + excludeModifiersCol: true, + excludeOverridesCol: true, + excludeSourcesCol: true, + leftAlignHeadings: true, + }, }, ], }, @@ -144,6 +168,9 @@ const config: Record = { entryPointStrategy: 'packages', name: 'packages-example', disableSources: true, + tableColumns: { + leftAlignHeadings: true, + }, }, options: [ { entryFileName: 'index.md' }, @@ -206,6 +233,9 @@ const config: Record = { commonOptions: { plugin: [path.join(__dirname, 'custom-plugins', 'navigation-plugin.mjs')], disableSources: true, + tableColumns: { + leftAlignHeadings: true, + }, }, options: [ { 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 02d5116a6..03cdfda56 100644 --- a/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts +++ b/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts @@ -140,3 +140,114 @@ export function multipleExampleTags() { export function singleExampleTag() { return true; } + +export class BaseClassProperties { + /** + * @deprecated + */ + propA: string; + propB: string; +} + +export class ClassPropertiesTable extends BaseClassProperties { + propA = 'propAValue'; + /** + * The subroutine recursively parsed the hexadecimal data. + * to generate the binary output for input validation. + */ + private prop1: boolean; + /** + * Below is a breakdown of the notable performances: + * + * - The CPU executed the instruction set in parallel with the GPU computations. + * - The RAM efficiently cached the frequently accessed data for faster retrieval. + * - The SSD accessed the stored files with lightning speed due to its high read/write capabilities. + */ + readonly prop2: RegExp; + /** + * ### Example of Triple Code Block + * + * ```python + * def greet(name): + * print("Hello, " + name + "!") + * ``` + */ + prop3?: string; +} + +export interface BaseInterfaceProperties { + /** + * @deprecated + */ + propA: string; + propB: string; +} + +export interface InterfacePropertiesTable extends BaseInterfaceProperties { + /** + * The subroutine recursively parsed the hexadecimal data. + * to generate the binary output for input validation. + */ + prop1: boolean; + /** + * Below is a breakdown of the notable performances: + * + * - The CPU executed the instruction set in parallel with the GPU computations. + * - The RAM efficiently cached the frequently accessed data for faster retrieval. + * - The SSD accessed the stored files with lightning speed due to its high read/write capabilities. + */ + prop2: RegExp; + /** + * ### Example of Triple Code Block + * + * ```python + * def greet(name): + * print("Hello, " + name + "!") + * ``` + */ + prop3?: string; +} + +export type TypeDeclarationTable = { + /** + * The subroutine recursively parsed the hexadecimal data. + * to generate the binary output for input validation. + */ + declaration1: boolean; + /** + * The subroutine recursively parsed the hexadecimal data. + * to generate the binary output for input validation. + */ + declaration2: boolean; + declaration3: 'declaration3'; +}; + +/** + * Adds two numbers together. + * + * @typeParam T The type of the numbers to be added. + * + * @param param1 The first param + * to be added. + * @param param2 The second param to be added. + * + * Some additional text for num2. + * + * @param param3 The third param to be added. + * + * + */ +export function parametersTable( + param1: number, + param2: number, + param3 = 4, +) { + return param1 + param2 + param3; +} + +export enum EnumMembersTable { + /** + * The subroutine recursively parsed the hexadecimal data. + */ + member1 = 'member1', +} 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 ad4ff25f8..e2df22429 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 @@ -79,13 +79,25 @@ This is a simple example on how to use include. ## Enumerations - [CommentEnum](enumerations/CommentEnum.md) +- [EnumMembersTable](enumerations/EnumMembersTable.md) + +## Classes + +- [BaseClassProperties](classes/BaseClassProperties.md) +- [ClassPropertiesTable](classes/ClassPropertiesTable.md) ## Interfaces +- [BaseInterfaceProperties](interfaces/BaseInterfaceProperties.md) - [CommentInterface](interfaces/CommentInterface.md) - [CommentInterfaceExtended](interfaces/CommentInterfaceExtended.md) +- [InterfacePropertiesTable](interfaces/InterfacePropertiesTable.md) - [SameName](interfaces/SameName.md) +## Type Aliases + +- [TypeDeclarationTable](type-aliases/TypeDeclarationTable.md) + ## Variables - [SameName](variables/SameName.md) @@ -96,499 +108,354 @@ This is a simple example on how to use include. ## Functions - [multipleExampleTags](functions/multipleExampleTags.md) +- [parametersTable](functions/parametersTable.md) - [singleExampleTag](functions/singleExampleTag.md) " `; -exports[`Comments should compile comments for module: (Output File Strategy "members") (Option Group "2") 1`] = ` -"# typedoc-stubs - -Comments form module comments - -## Links - -Links using \`{@link}\` inline tags. - -- [CommentInterface](http:/example.com/Interface.CommentInterface.mdx) - Links to CommentInterface -- [Links to CommentInterface.prop](http:/example.com/Interface.CommentInterface.mdx#prop) -- [Links to CommentInterface.propb](http:/example.com/Interface.CommentInterface.mdx#propb) -- [CommentEnum.MemberB](http:/example.com/Enumeration.CommentEnum.mdx#MemberB) -- [SameName:var](http:/example.com/Variable.SameName.mdx) -- [SameName:interface](http:/example.com/Interface.SameName.mdx) -- [SameName.prop](http:/example.com/Interface.SameName.mdx#prop) -- [prop:var](http:/example.com/Variable.prop.mdx) -- [_prop_with_underscore:var](http:/example.com/Variable._prop_with_underscore.mdx) - -External links: - -- [Google](https://www.google.com) -- [\`https://www.google.com\`](https://www.google.com) - -## Tag A - -Comments for a tag - -## Tag B - -Comments for tag written on same line - -## Html And Jsx - -A \\\\ in comments - -A \`\` in backticks - -Another object \`{ x: 1 }\`. - -\\
    - \\ -\\ - -Some random \\{\\{braces\\}\\}. - -\`\`\` -A in a code block -Some

    html

    inside codeblock -\`\`\` +exports[`Comments should get tables for emum: (Output File Strategy "members") (Option Group "1") 1`] = ` +"# Enumeration: EnumMembersTable -## Media - -You can include media in doc comments: - -![alt SomeAlt](media/logo.png) - -And include other files: +## Enumeration Members -This is a simple example on how to use include. - -![My image alt text](media/logo.png) - [[include:not-found.md]] - -## Code Blocks - -\`\`\`css -.class {color:red} -\`\`\` - -\`\`\`html -
    x
    y -\`\`\` - -\`single line {block}\` - -## Enumerations - -- [CommentEnum](http:/example.com/Enumeration.CommentEnum.mdx) - -## Interfaces - -- [CommentInterface](http:/example.com/Interface.CommentInterface.mdx) -- [CommentInterfaceExtended](http:/example.com/Interface.CommentInterfaceExtended.mdx) -- [SameName](http:/example.com/Interface.SameName.mdx) - -## Variables - -- [SameName](http:/example.com/Variable.SameName.mdx) -- [\\_prop\\_with\\_underscore](http:/example.com/Variable._prop_with_underscore.mdx) -- [prop](http:/example.com/Variable.prop.mdx) -- [propb](http:/example.com/Variable.propb.mdx) - -## Functions - -- [multipleExampleTags](http:/example.com/Function.multipleExampleTags.mdx) -- [singleExampleTag](http:/example.com/Function.singleExampleTag.mdx) +| Enumeration Member | Value | Description | +| ------ | ------ | ------ | +| \`member1\` | \`"member1"\` | The subroutine recursively parsed the hexadecimal data. | " `; -exports[`Comments should compile comments for module: (Output File Strategy "modules") (Option Group "1") 1`] = ` -"# typedoc-stubs +exports[`Comments should get tables for emum: (Output File Strategy "members") (Option Group "2") 1`] = ` +"# Enumeration: EnumMembersTable -Comments form module comments +## Enumeration Members -## Links + + + + + + + +
    Enumeration MemberValueDescription
    -Links using \`{@link}\` inline tags. - -- [CommentInterface](README.md#commentinterface) - Links to CommentInterface -- [Links to CommentInterface.prop](README.md#commentinterface) -- [Links to CommentInterface.propb](README.md#commentinterface) -- [CommentEnum.MemberB](README.md#commentenum) -- [SameName:var](README.md#samename-1) -- [SameName:interface](README.md#samename) -- [SameName.prop](README.md#samename) -- [prop:var](README.md#prop) -- [_prop_with_underscore:var](README.md#_prop_with_underscore) - -External links: + \`member1\` -- [Google](https://www.google.com) -- [\`https://www.google.com\`](https://www.google.com) + -## Tag A +\`"member1"\` -Comments for a tag + -## Tag B - -Comments for tag written on same line - -## Html And Jsx - -A in comments - -A \`\` in backticks - -Another object \`{ x: 1 }\`. - -
    - -
    - -Some random {{braces}}. - -\`\`\` -A in a code block -Some

    html

    inside codeblock -\`\`\` - -## Media - -You can include media in doc comments: - -![alt SomeAlt](media/logo.png) - -And include other files: - -This is a simple example on how to use include. - -![My image alt text](media/logo.png) - [[include:not-found.md]] - -## Code Blocks +The subroutine recursively parsed the hexadecimal data. -\`\`\`css -.class {color:red} -\`\`\` - -\`\`\`html -
    x
    y -\`\`\` - -\`single line {block}\` - -## Enumerations - -### CommentEnum - -#### Enumeration Members - -| Enumeration Member | Value | Description | -| :------ | :------ | :------ | -| \`Member\` | \`0\` |

    Comment for Member

    Some

    html

    and .

    **Deprecated**

    Deprecated member

    **See**

    [SameName](README.md#samename-1)

    | -| \`MemberB\` | \`1\` | - | - -## Interfaces - -### CommentInterface - -#### Extended by +
    +" +`; -- [\`CommentInterfaceExtended\`](README.md#commentinterfaceextended) +exports[`Comments should get tables for parameters: (Output File Strategy "members") (Option Group "1") 1`] = ` +"# Function: parametersTable() -#### Properties +> **parametersTable**\\<\`T\`\\>(\`param1\`, \`param2\`, \`param3\`): \`number\` -| Property | Type | -| :------ | :------ | -| \`prop\` | \`string\` | -| \`propb\` | \`string\` | +Adds two numbers together. -*** +## Type parameters -### CommentInterfaceExtended +| Type parameter | Value | Description | +| ------ | ------ | ------ | +| \`T\` | \`string\` | The type of the numbers to be added. | -#### Extends +## Parameters -- [\`CommentInterface\`](README.md#commentinterface) +| Parameter | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| \`param1\` | \`number\` | \`undefined\` | The first param to be added. | +| \`param2\` | \`number\` | \`undefined\` | The second param to be added. Some additional text for num2. | +| \`param3\` | \`number\` | \`4\` | The third param to be added. | -#### Properties +## Returns -| Property | Type | Inherited from | -| :------ | :------ | :------ | -| \`prop\` | \`string\` | [\`CommentInterface\`](README.md#commentinterface).\`prop\` | -| \`propb\` | \`string\` | [\`CommentInterface\`](README.md#commentinterface).\`propb\` | -| \`propc\` | \`string\` | - | +\`number\` +" +`; -*** +exports[`Comments should get tables for properties: (Output File Strategy "members") (Option Group "1") 1`] = ` +"# Class: ClassPropertiesTable -### SameName +## Extends -#### Properties +- [\`BaseClassProperties\`](BaseClassProperties.md) -| Property | Type | -| :------ | :------ | -| \`prop\` | \`string\` | -| \`propb\` | \`string\` | +## Constructors -## Variables +### new ClassPropertiesTable() -### SameName +> **new ClassPropertiesTable**(): [\`ClassPropertiesTable\`](ClassPropertiesTable.md) -> **SameName**: \`true\` +#### Returns -*** +[\`ClassPropertiesTable\`](ClassPropertiesTable.md) -### \\_prop\\_with\\_underscore +#### Inherited from -> \`const\` **\\_prop\\_with\\_underscore**: \`true\` = \`true\` +[\`BaseClassProperties\`](BaseClassProperties.md).[\`constructor\`](BaseClassProperties.md#constructors) -*** +## Properties -### prop +| Property | Modifier | Type | Default value | Description | Overrides | Inherited from | +| ------ | ------ | ------ | ------ | ------ | ------ | ------ | +| \`prop1\` | \`private\` | \`boolean\` | \`undefined\` | The subroutine recursively parsed the hexadecimal data. to generate the binary output for input validation. | - | - | +| \`prop2\` | \`readonly\` | \`RegExp\` | \`undefined\` | Below is a breakdown of the notable performances: - The CPU executed the instruction set in parallel with the GPU computations. - The RAM efficiently cached the frequently accessed data for faster retrieval. - The SSD accessed the stored files with lightning speed due to its high read/write capabilities. | - | - | +| \`prop3?\` | \`public\` | \`string\` | \`undefined\` | ### Example of Triple Code Block \`def greet(name): print("Hello, " + name + "!")\` | - | - | +| ~~\`propA\`~~ | \`public\` | \`string\` | \`'propAValue'\` | **Deprecated** | [\`BaseClassProperties\`](BaseClassProperties.md).\`propA\` | - | +| \`propB\` | \`public\` | \`string\` | \`undefined\` | - | - | [\`BaseClassProperties\`](BaseClassProperties.md).\`propB\` | +" +`; -> \`const\` **prop**: \`true\` = \`true\` +exports[`Comments should get tables for properties: (Output File Strategy "members") (Option Group "2") 1`] = ` +"# Class: ClassPropertiesTable -*** +## Extends -### propb +- [\`BaseClassProperties\`](http:/example.com/Class.BaseClassProperties.md) -> \`const\` **propb**: \`true\` = \`true\` +## Constructors -## Functions + -### multipleExampleTags() +### new ClassPropertiesTable() -> **multipleExampleTags**(): \`boolean\` - -Function with multiple example tags +> **new ClassPropertiesTable**(): [\`ClassPropertiesTable\`](http:/example.com/Class.ClassPropertiesTable.md) #### 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. +[\`ClassPropertiesTable\`](http:/example.com/Class.ClassPropertiesTable.md) -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) -\`\`\` +#### Inherited from -*** +[\`BaseClassProperties\`](http:/example.com/Class.BaseClassProperties.md).[\`constructor\`](http:/example.com/Class.BaseClassProperties.md#Constructors) -### singleExampleTag() +## Properties -> **singleExampleTag**(): \`boolean\` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    PropertyTypeDefault valueDescription
    -Function with single example tag + \`prop1\` -#### 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) -\`\`\` -" -`; - -exports[`Comments should compile comments for module: (Output File Strategy "modules") (Option Group "2") 1`] = ` -"# typedoc-stubs - -Comments form module comments - -## Links + -Links using \`{@link}\` inline tags. +\`undefined\` -- [CommentInterface](http:/example.com/README.mdx#CommentInterface) - Links to CommentInterface -- [Links to CommentInterface.prop](http:/example.com/README.mdx#prop) -- [Links to CommentInterface.propb](http:/example.com/README.mdx#propb) -- [CommentEnum.MemberB](http:/example.com/README.mdx#MemberB) -- [SameName:var](http:/example.com/README.mdx#SameName-1) -- [SameName:interface](http:/example.com/README.mdx#SameName) -- [SameName.prop](http:/example.com/README.mdx#prop-2) -- [prop:var](http:/example.com/README.mdx#prop-3) -- [_prop_with_underscore:var](http:/example.com/README.mdx#_prop_with_underscore) + -External links: +The subroutine recursively parsed the hexadecimal data. +to generate the binary output for input validation. -- [Google](https://www.google.com) -- [\`https://www.google.com\`](https://www.google.com) +
    -## Tag A + \`prop2\` -Comments for a tag + -## Tag B +\`RegExp\` -Comments for tag written on same line + -## Html And Jsx +\`undefined\` -A \\\\ in comments + -A \`\` in backticks +Below is a breakdown of the notable performances: -Another object \`{ x: 1 }\`. +- The CPU executed the instruction set in parallel with the GPU computations. +- The RAM efficiently cached the frequently accessed data for faster retrieval. +- The SSD accessed the stored files with lightning speed due to its high read/write capabilities. -\\
    - \\ -\\ +
    -Some random \\{\\{braces\\}\\}. + \`prop3?\` -\`\`\` -A in a code block -Some

    html

    inside codeblock -\`\`\` +
    -## Media +\`string\` -You can include media in doc comments: + -![alt SomeAlt](media/logo.png) +\`undefined\` -And include other files: + -This is a simple example on how to use include. +### Example of Triple Code Block -![My image alt text](media/logo.png) - [[include:not-found.md]] - -## Code Blocks - -\`\`\`css -.class {color:red} +\`\`\`python +def greet(name): +print("Hello, " + name + "!") \`\`\` -\`\`\`html -
    x
    y -\`\`\` - -\`single line {block}\` +
    -## Enumerations + ~~\`propA\`~~ - + -### CommentEnum +\`string\` -#### Enumeration Members + -| Enumeration Member | Value | Description | -| :------ | :------ | :------ | -| \`Member\` | \`0\` |

    Comment for Member

    Some \\ html \\ and \\\\.

    **Deprecated**

    Deprecated member

    **See**

    [SameName](http:/example.com/README.mdx#SameName-1)

    | -| \`MemberB\` | \`1\` | - | +\`'propAValue'\` -## Interfaces +
    - +**Deprecated** -### CommentInterface +
    -#### Extended by + \`propB\` -- [\`CommentInterfaceExtended\`](http:/example.com/README.mdx#CommentInterfaceExtended) + -#### Properties +\`string\` -| Property | Type | -| :------ | :------ | -| \`prop\` | \`string\` | -| \`propb\` | \`string\` | + -*** +\`undefined\` - + -### CommentInterfaceExtended +‐ -#### Extends +
    +" +`; -- [\`CommentInterface\`](http:/example.com/README.mdx#CommentInterface) +exports[`Comments should get tables for type declarations: (Output File Strategy "members") (Option Group "1") 1`] = ` +"# Type alias: TypeDeclarationTable -#### Properties +> **TypeDeclarationTable**: \`object\` -| Property | Type | Inherited from | -| :------ | :------ | :------ | -| \`prop\` | \`string\` | [\`CommentInterface\`](http:/example.com/README.mdx#CommentInterface).[\`prop\`](http:/example.com/README.mdx#prop) | -| \`propb\` | \`string\` | [\`CommentInterface\`](http:/example.com/README.mdx#CommentInterface).[\`propb\`](http:/example.com/README.mdx#propb) | -| \`propc\` | \`string\` | - | +## Type declaration -*** +| Member | Type | Description | +| ------ | ------ | ------ | +| \`declaration1\` | \`boolean\` | The subroutine recursively parsed the hexadecimal data. to generate the binary output for input validation. | +| \`declaration2\` | \`boolean\` | The subroutine recursively parsed the hexadecimal data. to generate the binary output for input validation. | +| \`declaration3\` | \`"declaration3"\` | - | +" +`; - +exports[`Comments should get tables for type declarations: (Output File Strategy "members") (Option Group "2") 1`] = ` +"# Type alias: TypeDeclarationTable -### SameName +> **TypeDeclarationTable**: \`object\` -#### Properties +## Type declaration -| Property | Type | -| :------ | :------ | -| \`prop\` | \`string\` | -| \`propb\` | \`string\` | + + + + + + + + + + + + + + + + + +
    MemberTypeDescription
    -## Variables +\`declaration1\` - + -### SameName +\`boolean\` -> **SameName**: \`true\` + -*** +The subroutine recursively parsed the hexadecimal data. +to generate the binary output for input validation. - +
    -### \\_prop\\_with\\_underscore +\`declaration2\` -> \`const\` **\\_prop\\_with\\_underscore**: \`true\` = \`true\` + -*** +\`boolean\` - + -### prop +The subroutine recursively parsed the hexadecimal data. +to generate the binary output for input validation. -> \`const\` **prop**: \`true\` = \`true\` +
    -*** +\`declaration3\` - + -### propb +\`"declaration3"\` -> \`const\` **propb**: \`true\` = \`true\` + -## Functions +‐ - +
    +" +`; -### multipleExampleTags() +exports[`Comments should handle multiple example tags: (Output File Strategy "members") (Option Group "1") 1`] = ` +"# Function: multipleExampleTags() > **multipleExampleTags**(): \`boolean\` Function with multiple example tags -#### Returns +## Returns \`boolean\` -#### Examples +## Examples \`\`\`ts // If there are no code blocks, TypeDoc assumes the whole tag @@ -604,22 +471,29 @@ text outside of the code block as regular text. \`\`\`ts factorial(1) \`\`\` +" +`; -*** +exports[`Comments should handle single example tags: (Output File Strategy "members") (Option Group "1") 1`] = ` +"# Function: multipleExampleTags() - +> **multipleExampleTags**(): \`boolean\` -### singleExampleTag() +Function with multiple example tags -> **singleExampleTag**(): \`boolean\` +## Returns -Function with single example tag +\`boolean\` -#### Returns +## Examples -\`boolean\` +\`\`\`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. -#### Example +factorial(1) +\`\`\` 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__/objects-and-params.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/objects-and-params.spec.ts.snap index b1c94dd9e..e39abd22e 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 @@ -204,7 +204,7 @@ Comments for BasicInterface | Property | Type | Description | | :------ | :------ | :------ | -| ~~\`deprecatedProp\`~~ | \`string\` |

    **Deprecated**

    This prop is deprecated

    **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.class.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.class.spec.ts.snap index 552dbb814..174cf1f25 100644 --- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.class.spec.ts.snap +++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.class.spec.ts.snap @@ -1010,9 +1010,9 @@ new ClassWithSimpleProps(): ClassWithSimpleProps | Property | Type | Default value | Description | | :------ | :------ | :------ | :------ | | \`propA\` | \`string\` | \`'propAValue'\` | Comments for propA | -| \`propB\` | \`string\` | 'propBDefaultValue' |

    Comments for propB

    | -| \`propC\` | \`string\` | 'propCDefaultValue' |

    Comments for propB on two lines

    | -| \`propD\` | \`string\` | \`undefined\` |

    Comments for propE

    **Tag**

    SomeTag

    | +| \`propB\` | \`string\` | \`'propBDefaultValue'\` | Comments for propB | +| \`propC\` | \`string\` | \`'propCDefaultValue'\` | Comments for propB on two lines | +| \`propD\` | \`string\` | \`undefined\` | Comments for propE **Tag** SomeTag | " `; 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 44143588b..a2cfd0ad4 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 @@ -244,7 +244,7 @@ Comments for BasicInterface | Property | Type | Description | | :------ | :------ | :------ | -| ~~\`deprecatedProp\`~~ | \`string\` |

    **Deprecated**

    This prop is deprecated

    **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 | @@ -559,7 +559,7 @@ Comments for ExtendedInterface | Property | Type | Description | Inherited from | | :------ | :------ | :------ | :------ | -| ~~\`deprecatedProp\`~~ | \`string\` |

    **Deprecated**

    This prop is deprecated

    **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\` | @@ -692,14 +692,14 @@ And some more comments | :------ | :------ | | \`A\` | This is a parameter. | | \`B\` | Comments for a parameter. This sentence is on a soft new line. | -| \`C\` |

    This is a parameter.

    Documentation with a double line

    | -| \`D\` |

    These are comments with paras

    These are comments with paras

    Other comments Comments with

    paras

    These are comments with paras

    | +| \`C\` | This is a parameter. Documentation with a double line | +| \`D\` |

    These are comments with paras

    These are comments with paras

    Other comments Comments with

    paras

    These are comments with paras

    | ## Properties | Property | Type | Description | | :------ | :------ | :------ | -| ~~\`propertyWithComments\`~~ | \`string\` |

    Some text.

    • list item
    • list item

    **Deprecated**

    This is a deprecated property

    **See**

    https://example.com

    | +| ~~\`propertyWithComments\`~~ | \`string\` | Some text. - list item - list item **Deprecated** This is a deprecated property **See** https://example.com | " `; @@ -770,7 +770,7 @@ exports[`Interface Reflection should compile interface with event properties: (O | Event | Type | Description | | :------ | :------ | :------ | | \`anotherEvent\` | \`MouseEvent\` | - | -| ~~\`someEvent?\`~~ | (\`eventParam\`: [\`CustomEventInterface\`](CustomEventInterface.md)\\<\`MouseEvent\`\\>) => \`void\` |

    Description for event someEvent

    **Deprecated**

    Deprectaed comments

    | +| ~~\`someEvent?\`~~ | (\`eventParam\`: [\`CustomEventInterface\`](CustomEventInterface.md)\\<\`MouseEvent\`\\>) => \`void\` | Description for event someEvent **Deprecated** Deprectaed comments | " `; diff --git a/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts b/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts index e458bb9c2..d719917ab 100644 --- a/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts +++ b/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts @@ -2,10 +2,47 @@ import { expectFileToEqual } from '@devtools/testing'; describe(`Comments`, () => { test(`should compile comments for module`, () => { + expectFileToEqual('comments', ['members'], ['README.md']); + }); + + test(`should handle single example tags`, () => { + expectFileToEqual( + 'comments', + ['members'], + ['/functions/multipleExampleTags.md'], + ); + }); + + test(`should handle multiple example tags`, () => { expectFileToEqual( 'comments', - ['modules', 'members'], - ['README.md', 'README.mdx'], + ['members'], + ['/functions/multipleExampleTags.md'], ); }); + + test(`should get tables for properties`, () => { + expectFileToEqual('comments', 'members', [ + '/classes/ClassPropertiesTable.md', + '/Class.ClassPropertiesTable.md', + ]); + }); + + test(`should get tables for parameters`, () => { + expectFileToEqual('comments', 'members', ['/functions/parametersTable.md']); + }); + + test(`should get tables for type declarations`, () => { + expectFileToEqual('comments', 'members', [ + '/type-aliases/TypeDeclarationTable.md', + '/Type.TypeDeclarationTable.md', + ]); + }); + + test(`should get tables for emum`, () => { + expectFileToEqual('comments', 'members', [ + '/enumerations/EnumMembersTable.md', + '/Enumeration.EnumMembersTable.md', + ]); + }); });