diff --git a/.changeset/yellow-beds-smile.md b/.changeset/yellow-beds-smile.md index 7becadfcd..561722500 100644 --- a/.changeset/yellow-beds-smile.md +++ b/.changeset/yellow-beds-smile.md @@ -1,5 +1,6 @@ --- -"typedoc-plugin-markdown": patch +'typedoc-plugin-markdown': patch --- - Remove superfluous quotes from prop names (#619) +- Fix display of index descriptions in tables (#619) diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-declaration-comment.ts b/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-declaration-comment.ts index e040bbf13..04ed234cc 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-declaration-comment.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-declaration-comment.ts @@ -4,8 +4,5 @@ export function getDeclarationComment(model: DeclarationReflection) { if (model.signatures?.length) { return model.signatures[0].comment; } - if ((model.type as any)?.declaration?.signatures?.length) { - return (model.type as any)?.declaration.signatures[0].comment; - } return model.comment; } diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/index.ts b/packages/typedoc-plugin-markdown/src/theme/resources/index.ts index edccdfd88..b0392ce43 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/index.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/index.ts @@ -596,7 +596,7 @@ There is no association list partial for properties as these are handled as a st export const helpers = (context: MarkdownThemeContext) => { return { getDeclarationComment: (model: DeclarationReflection) => - getDeclarationComment.apply(context, [model]) as any, + getDeclarationComment.apply(context, [model]) as Comment | undefined, getDeclarationType: (model: DeclarationReflection) => getDeclarationType.apply(context, [model]) as SomeType | undefined, getFlattenedDeclarations: ( 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 2dedc1df7..9e62c1620 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 @@ -110,7 +110,12 @@ function getTable( const comment = context.helpers.getDeclarationComment(child); if (comment?.summary?.length) { - row.push(context.partials.commentParts(comment.summary)?.split('\n')[0]); + row.push( + context.partials + .commentParts(comment.summary) + ?.split('\n\n')[0] + .replace(/\n/g, ' '), + ); } else { row.push('-'); } diff --git a/packages/typedoc-plugin-markdown/test/fixtures/config.ts b/packages/typedoc-plugin-markdown/test/fixtures/config.ts index 9049d8e21..c2f78ec9e 100644 --- a/packages/typedoc-plugin-markdown/test/fixtures/config.ts +++ b/packages/typedoc-plugin-markdown/test/fixtures/config.ts @@ -76,7 +76,11 @@ const config: Record = { only: false, entryPoints: '/groups/**/*.ts', commonOptions: { - plugin: [path.join(__dirname, 'custom-plugins', 'navigation-plugin.mjs')], + plugin: [ + path.join(__dirname, 'custom-plugins', 'stub-groups-theme.mjs'), + path.join(__dirname, 'custom-plugins', 'navigation-plugin.mjs'), + ], + theme: 'stub-groups', disableSources: true, entryFileName: 'index.md', }, @@ -89,7 +93,13 @@ const config: Record = { }, { readme: 'none', - membersWithOwnFile: ['Class', 'Interface', 'Enum'], + membersWithOwnFile: [ + 'Class', + 'Interface', + 'Enum', + 'TypeAlias', + 'Function', + ], excludeGroups: true, useHTMLAnchors: true, indexFormat: 'table', diff --git a/packages/typedoc-plugin-markdown/test/fixtures/custom-plugins/stub-groups-theme.mjs b/packages/typedoc-plugin-markdown/test/fixtures/custom-plugins/stub-groups-theme.mjs new file mode 100644 index 000000000..0eb20f861 --- /dev/null +++ b/packages/typedoc-plugin-markdown/test/fixtures/custom-plugins/stub-groups-theme.mjs @@ -0,0 +1,30 @@ +// @ts-check +import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown'; + +/** + * @param {import('typedoc-plugin-markdown').MarkdownApplication} app + */ +export function load(app) { + app.renderer.defineTheme('stub-groups', StubPartialsTheme); +} + +class StubPartialsTheme extends MarkdownTheme { + /** + * @param {import('typedoc-plugin-markdown').MarkdownPageEvent} page + */ + getRenderContext(page) { + return new MyMarkdownThemeContext(this, page, this.application.options); + } +} + +class MyMarkdownThemeContext extends MarkdownThemeContext { + partials = { + ...this.partials, + declaration: () => { + return `_DECLARATION_MEMBER_PARTIAL_`; + }, + signature: () => { + return `_SIGNATURE_MEMBER_PARTIAL_`; + }, + }; +} diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/groups/basic.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/groups/basic.ts index c1bf829f7..286e39ced 100644 --- a/packages/typedoc-plugin-markdown/test/fixtures/src/groups/basic.ts +++ b/packages/typedoc-plugin-markdown/test/fixtures/src/groups/basic.ts @@ -3,14 +3,46 @@ * * @module */ + +/** + * Interface A comments line 1 + * and comments on a soft line. + * + * Comments on double new line. + */ export interface InterfaceA { propA: string; propB: string; } + +/** + * InterfaceB function. + */ export interface InterfaceB {} +/** + * EnumA function. + */ export enum EnumA {} export enum EnumB {} +/** + * ClassA function. + */ export class ClassA {} export class ClassB {} +/** + * TypeA function. + */ export type TypeA = string; -export type TypeB = string; +/** + * TypeB function. + * + * @param str - A string to tokenize. + * @param offset - Initial offset. Used when composing lexers. + */ +export type TypeB = (str: string, offset?: number) => any; +/** + * functionA function. + */ +export function functionA() {} +export const variableA = ''; +export const variableB = ''; diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/groups.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/groups.spec.ts.snap index 2bfdcc2aa..7aec8e807 100644 --- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/groups.spec.ts.snap +++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/groups.spec.ts.snap @@ -32,6 +32,15 @@ A basic module - [TypeA](type-aliases/TypeA.md) - [TypeB](type-aliases/TypeB.md) + +### Variables + +- [variableA](variables/variableA.md) +- [variableB](variables/variableB.md) + +### Functions + +- [functionA](functions/functionA.md) " `; @@ -50,26 +59,29 @@ A basic module | Member | Description | | :------ | :------ | -| [EnumA](enumerations/EnumA.md) | - | +| [EnumA](enumerations/EnumA.md) | EnumA function. | | [EnumB](enumerations/EnumB.md) | - | -| [ClassA](classes/ClassA.md) | - | +| [ClassA](classes/ClassA.md) | ClassA function. | | [ClassB](classes/ClassB.md) | - | -| [InterfaceA](interfaces/InterfaceA.md) | - | -| [InterfaceB](interfaces/InterfaceB.md) | - | +| [InterfaceA](interfaces/InterfaceA.md) | Interface A comments line 1 and comments on a soft line. | +| [InterfaceB](interfaces/InterfaceB.md) | InterfaceB function. | +| [TypeA](type-aliases/TypeA.md) | TypeA function. | +| [TypeB](type-aliases/TypeB.md) | TypeB function. | +| [functionA](functions/functionA.md) | functionA function. | - + -## TypeA +## variableA -> **TypeA**: \`string\` +_DECLARATION_MEMBER_PARTIAL_ *** - + -## TypeB +## variableB -> **TypeB**: \`string\` +_DECLARATION_MEMBER_PARTIAL_ " `; @@ -88,6 +100,8 @@ A basic module ### EnumA +EnumA function. + *** ### EnumB @@ -96,15 +110,13 @@ A basic module ### ClassA +ClassA function. + #### Constructors ##### new ClassA() -> **new ClassA**(): [\`ClassA\`](basic.md#classa) - -###### Returns - -[\`ClassA\`](basic.md#classa) +_SIGNATURE_MEMBER_PARTIAL_ *** @@ -114,41 +126,62 @@ A basic module ##### new ClassB() -> **new ClassB**(): [\`ClassB\`](basic.md#classb) - -###### Returns - -[\`ClassB\`](basic.md#classb) +_SIGNATURE_MEMBER_PARTIAL_ ## Interfaces ### InterfaceA +Interface A comments line 1 +and comments on a soft line. + +Comments on double new line. + #### Properties ##### propA -> **propA**: \`string\` +_DECLARATION_MEMBER_PARTIAL_ ##### propB -> **propB**: \`string\` +_DECLARATION_MEMBER_PARTIAL_ *** ### InterfaceB +InterfaceB function. + ## Type Aliases ### TypeA -> **TypeA**: \`string\` +_DECLARATION_MEMBER_PARTIAL_ *** -### TypeB +### TypeB() + +_DECLARATION_MEMBER_PARTIAL_ + +## Variables + +### variableA + +_DECLARATION_MEMBER_PARTIAL_ + +*** + +### variableB -> **TypeB**: \`string\` +_DECLARATION_MEMBER_PARTIAL_ + +## Functions + +### functionA() + +_SIGNATURE_MEMBER_PARTIAL_ " `; @@ -167,6 +200,8 @@ A basic module ## EnumA +EnumA function. + *** @@ -179,17 +214,15 @@ A basic module ## ClassA +ClassA function. + ### Constructors #### new ClassA() -> **new ClassA**(): [\`ClassA\`](basic.md#classa) - -##### Returns - -[\`ClassA\`](basic.md#classa) +_SIGNATURE_MEMBER_PARTIAL_ *** @@ -203,11 +236,7 @@ A basic module #### new ClassB() -> **new ClassB**(): [\`ClassB\`](basic.md#classb) - -##### Returns - -[\`ClassB\`](basic.md#classb) +_SIGNATURE_MEMBER_PARTIAL_ *** @@ -215,19 +244,24 @@ A basic module ## InterfaceA +Interface A comments line 1 +and comments on a soft line. + +Comments on double new line. + ### Properties #### propA -> **propA**: \`string\` +_DECLARATION_MEMBER_PARTIAL_ #### propB -> **propB**: \`string\` +_DECLARATION_MEMBER_PARTIAL_ *** @@ -235,21 +269,47 @@ A basic module ## InterfaceB +InterfaceB function. + *** ## TypeA -> **TypeA**: \`string\` +_DECLARATION_MEMBER_PARTIAL_ *** -## TypeB +## TypeB() + +_DECLARATION_MEMBER_PARTIAL_ + +*** -> **TypeB**: \`string\` + + +## variableA + +_DECLARATION_MEMBER_PARTIAL_ + +*** + + + +## variableB + +_DECLARATION_MEMBER_PARTIAL_ + +*** + + + +## functionA() + +_SIGNATURE_MEMBER_PARTIAL_ " `; @@ -513,7 +573,7 @@ A module that contains custom groupings ## variabelA -> \`const\` **variabelA**: \`true\` = \`true\` +_DECLARATION_MEMBER_PARTIAL_ *** @@ -521,7 +581,7 @@ A module that contains custom groupings ## variableB1 -> \`const\` **variableB1**: \`true\` = \`true\` +_DECLARATION_MEMBER_PARTIAL_ *** @@ -529,7 +589,7 @@ A module that contains custom groupings ## variableB2 -> \`const\` **variableB2**: \`true\` = \`true\` +_DECLARATION_MEMBER_PARTIAL_ *** @@ -537,9 +597,7 @@ A module that contains custom groupings ## variableC -> \`const\` **variableC**: \`true\` = \`true\` - -Default grouping +_DECLARATION_MEMBER_PARTIAL_ " `; @@ -781,28 +839,16 @@ A module that contains namespaces | [\\_\\_Class\\_A\\_](classes/Class_A.md) | - | | [InterfaceB](interfaces/InterfaceB.md) | - | | [\\_Interface\\_A\\_](interfaces/Interface_A.md) | - | - - - -## TypeB - -> **TypeB**: \`string\` - -*** - - - -## \\_Type\\_A\\_ - -> **\\_Type\\_A\\_**: \`string\` - -*** +| [TypeB](type-aliases/TypeB.md) | - | +| [\\_Type\\_A\\_](type-aliases/Type_A.md) | - | +| [\\_function\\_A\\_](functions/function_A.md) | - | +| [functionB](functions/functionB.md) | - | ## \\_variable\\_A\\_ -> \`const\` **\\_variable\\_A\\_**: \`true\` = \`true\` +_DECLARATION_MEMBER_PARTIAL_ *** @@ -810,31 +856,7 @@ A module that contains namespaces ## variableB -> \`const\` **variableB**: \`true\` = \`true\` - -*** - - - -## \\_function\\_A\\_() - -> **\\_function\\_A\\_**(): \`void\` - -### Returns - -\`void\` - -*** - - - -## functionB() - -> **functionB**(): \`void\` - -### Returns - -\`void\` +_DECLARATION_MEMBER_PARTIAL_ " `; @@ -872,11 +894,7 @@ A module that contains namespaces ##### new ClassB() -> **new ClassB**(): [\`ClassB\`](index.md#classb) - -###### Returns - -[\`ClassB\`](index.md#classb) +_SIGNATURE_MEMBER_PARTIAL_ *** @@ -886,11 +904,7 @@ A module that contains namespaces ##### new \\_\\_Class\\_A\\_() -> **new \\_\\_Class\\_A\\_**(): [\`__Class_A_\`](index.md#__class_a_) - -###### Returns - -[\`__Class_A_\`](index.md#__class_a_) +_SIGNATURE_MEMBER_PARTIAL_ ## Interfaces @@ -904,45 +918,37 @@ A module that contains namespaces ### TypeB -> **TypeB**: \`string\` +_DECLARATION_MEMBER_PARTIAL_ *** ### \\_Type\\_A\\_ -> **\\_Type\\_A\\_**: \`string\` +_DECLARATION_MEMBER_PARTIAL_ ## Variables ### \\_variable\\_A\\_ -> \`const\` **\\_variable\\_A\\_**: \`true\` = \`true\` +_DECLARATION_MEMBER_PARTIAL_ *** ### variableB -> \`const\` **variableB**: \`true\` = \`true\` +_DECLARATION_MEMBER_PARTIAL_ ## Functions ### \\_function\\_A\\_() -> **\\_function\\_A\\_**(): \`void\` - -#### Returns - -\`void\` +_SIGNATURE_MEMBER_PARTIAL_ *** ### functionB() -> **functionB**(): \`void\` - -#### Returns - -\`void\` +_SIGNATURE_MEMBER_PARTIAL_ " `; @@ -986,11 +992,7 @@ A module that contains namespaces #### new ClassB() -> **new ClassB**(): [\`ClassB\`](index.md#classb) - -##### Returns - -[\`ClassB\`](index.md#classb) +_SIGNATURE_MEMBER_PARTIAL_ *** @@ -1004,11 +1006,7 @@ A module that contains namespaces #### new \\_\\_Class\\_A\\_() -> **new \\_\\_Class\\_A\\_**(): [\`__Class_A_\`](index.md#__class_a_) - -##### Returns - -[\`__Class_A_\`](index.md#__class_a_) +_SIGNATURE_MEMBER_PARTIAL_ *** @@ -1028,7 +1026,7 @@ A module that contains namespaces ## TypeB -> **TypeB**: \`string\` +_DECLARATION_MEMBER_PARTIAL_ *** @@ -1036,7 +1034,7 @@ A module that contains namespaces ## \\_Type\\_A\\_ -> **\\_Type\\_A\\_**: \`string\` +_DECLARATION_MEMBER_PARTIAL_ *** @@ -1044,7 +1042,7 @@ A module that contains namespaces ## \\_variable\\_A\\_ -> \`const\` **\\_variable\\_A\\_**: \`true\` = \`true\` +_DECLARATION_MEMBER_PARTIAL_ *** @@ -1052,7 +1050,7 @@ A module that contains namespaces ## variableB -> \`const\` **variableB**: \`true\` = \`true\` +_DECLARATION_MEMBER_PARTIAL_ *** @@ -1060,11 +1058,7 @@ A module that contains namespaces ## \\_function\\_A\\_() -> **\\_function\\_A\\_**(): \`void\` - -### Returns - -\`void\` +_SIGNATURE_MEMBER_PARTIAL_ *** @@ -1072,11 +1066,7 @@ A module that contains namespaces ## functionB() -> **functionB**(): \`void\` - -### Returns - -\`void\` +_SIGNATURE_MEMBER_PARTIAL_ " `; @@ -1126,11 +1116,7 @@ Renames and re-exports [defaultFunction](has-references.md#defaultfunction) ### defaultFunction() -> **defaultFunction**(): \`string\` - -#### Returns - -\`string\` +_SIGNATURE_MEMBER_PARTIAL_ " `; @@ -1167,11 +1153,7 @@ Renames and re-exports [defaultFunction](has-references.md#defaultfunction) ## defaultFunction() -> **defaultFunction**(): \`string\` - -### Returns - -\`string\` +_SIGNATURE_MEMBER_PARTIAL_ " `; @@ -1223,6 +1205,12 @@ exports[`Groups should compile references index page: (Output File Strategy "mem A module that contains references +## Index + +| Member | Description | +| :------ | :------ | +| [defaultFunction](functions/defaultFunction.md) | - | + ## InterfaceA @@ -1243,18 +1231,6 @@ Renames and re-exports [InterfaceB](../basic/interfaces/InterfaceB.md) ## default -Renames and re-exports [defaultFunction](index.md#defaultfunction) - -*** - - - -## defaultFunction() - -> **defaultFunction**(): \`string\` - -### Returns - -\`string\` +Renames and re-exports [defaultFunction](functions/defaultFunction.md) " `; diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/navigation.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/navigation.spec.ts.snap index fec516060..bb0216835 100644 --- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/navigation.spec.ts.snap +++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/navigation.spec.ts.snap @@ -2044,6 +2044,21 @@ exports[`Navigation should gets Navigation Json for multiple entry points: (Outp "title": "TypeB", "kind": 2097152, "path": "basic/type-aliases/TypeB.md" + }, + { + "title": "variableA", + "kind": 32, + "path": "basic/variables/variableA.md" + }, + { + "title": "variableB", + "kind": 32, + "path": "basic/variables/variableB.md" + }, + { + "title": "functionA", + "kind": 64, + "path": "basic/functions/functionA.md" } ] }, @@ -2332,6 +2347,31 @@ exports[`Navigation should gets Navigation Json for multiple entry points: (Outp "path": "basic/interfaces/InterfaceB.md" } ] + }, + { + "title": "Type Aliases", + "children": [ + { + "title": "TypeA", + "kind": 2097152, + "path": "basic/type-aliases/TypeA.md" + }, + { + "title": "TypeB", + "kind": 2097152, + "path": "basic/type-aliases/TypeB.md" + } + ] + }, + { + "title": "Functions", + "children": [ + { + "title": "functionA", + "kind": 64, + "path": "basic/functions/functionA.md" + } + ] } ] }, @@ -2510,13 +2550,55 @@ exports[`Navigation should gets Navigation Json for multiple entry points: (Outp "path": "has-namespaces/interfaces/Interface_A.md" } ] + }, + { + "title": "Type Aliases", + "children": [ + { + "title": "TypeB", + "kind": 2097152, + "path": "has-namespaces/type-aliases/TypeB.md" + }, + { + "title": "_Type_A_", + "kind": 2097152, + "path": "has-namespaces/type-aliases/Type_A.md" + } + ] + }, + { + "title": "Functions", + "children": [ + { + "title": "_function_A_", + "kind": 64, + "path": "has-namespaces/functions/function_A.md" + }, + { + "title": "functionB", + "kind": 64, + "path": "has-namespaces/functions/functionB.md" + } + ] } ] }, { "title": "has-references", "kind": 2, - "path": "has-references/index.md" + "path": "has-references/index.md", + "children": [ + { + "title": "Functions", + "children": [ + { + "title": "defaultFunction", + "kind": 64, + "path": "has-references/functions/defaultFunction.md" + } + ] + } + ] }, { "title": "has-same-exports", diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap index 9c64bf065..ce87a0168 100644 --- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap +++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap @@ -198,11 +198,14 @@ exports[`Urls should gets Urls for multiple entry points: outputFileStrategy: me "basic/classes/ClassB.md", "basic/enumerations/EnumA.md", "basic/enumerations/EnumB.md", + "basic/functions/functionA.md", "basic/index.md", "basic/interfaces/InterfaceA.md", "basic/interfaces/InterfaceB.md", "basic/type-aliases/TypeA.md", "basic/type-aliases/TypeB.md", + "basic/variables/variableA.md", + "basic/variables/variableB.md", "has-categories/enumerations/CategoryAEnum1.md", "has-categories/enumerations/CategoryAEnum2.md", "has-categories/enumerations/CategoryBEnum1.md", @@ -257,9 +260,12 @@ exports[`Urls should gets Urls for multiple entry points: outputFileStrategy: me "basic/classes/ClassB.md", "basic/enumerations/EnumA.md", "basic/enumerations/EnumB.md", + "basic/functions/functionA.md", "basic/index.md", "basic/interfaces/InterfaceA.md", "basic/interfaces/InterfaceB.md", + "basic/type-aliases/TypeA.md", + "basic/type-aliases/TypeB.md", "has-categories/enumerations/CategoryAEnum1.md", "has-categories/enumerations/CategoryAEnum2.md", "has-categories/enumerations/CategoryBEnum1.md", @@ -276,6 +282,8 @@ exports[`Urls should gets Urls for multiple entry points: outputFileStrategy: me "has-namespaces/classes/Class_A.md", "has-namespaces/enumerations/EnumB.md", "has-namespaces/enumerations/Enum_A.md", + "has-namespaces/functions/functionB.md", + "has-namespaces/functions/function_A.md", "has-namespaces/index.md", "has-namespaces/interfaces/InterfaceB.md", "has-namespaces/interfaces/Interface_A.md", @@ -284,6 +292,9 @@ exports[`Urls should gets Urls for multiple entry points: outputFileStrategy: me "has-namespaces/namespaces/Namespace_A/interfaces/NamespaceInterface.md", "has-namespaces/namespaces/Namespace_A/namespaces/NestedNamespace/index.md", "has-namespaces/namespaces/Namespace_A/namespaces/NestedNamespace/interfaces/NamespaceInterface.md", + "has-namespaces/type-aliases/TypeB.md", + "has-namespaces/type-aliases/Type_A.md", + "has-references/functions/defaultFunction.md", "has-references/index.md", "has-same-exports/classes/SomeClass.md", "has-same-exports/classes/someClass-1.md",