diff --git a/packages/ts-docs-gen/examples/simple/docs/api/index.md b/packages/ts-docs-gen/examples/simple/docs/api/index.md index ec6bea08..e3b4a381 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index.md @@ -1,10 +1,10 @@ -[InterfaceDeclaration-1]: index.md#foo -[InterfaceDeclaration-2]: index.md#boo -[InterfaceDeclaration-4]: index.md#myconstrainttype -[InterfaceDeclaration-9]: index.md#dictionary -[InterfaceDeclaration-9]: index.md#dictionary -[InterfaceDeclaration-6]: index.md#objectsinterface -[InterfaceDeclaration-12]: index.md#monsterinterface +[InterfaceDeclaration-1]: index.md#interface-foo +[InterfaceDeclaration-2]: index.md#interface-boo +[InterfaceDeclaration-4]: index.md#interface-myconstrainttype +[InterfaceDeclaration-9]: index.md#interface-dictionary +[InterfaceDeclaration-9]: index.md#interface-dictionary +[InterfaceDeclaration-6]: index.md#interface-objectsinterface +[InterfaceDeclaration-12]: index.md#interface-monsterinterface [ClassDeclaration-0]: index/hello.md#hello # index @@ -80,26 +80,23 @@ interface AnotherInterface { (param1: TValue, param2: TValue): boolean ``` -Type parameters: +**Type parameters:** | Name | | ------ | | TValue | -Parameters: +**Parameters:** | Name | Type | | ------ | ------ | | param1 | TValue | | param2 | TValue | -Return type: +**Return type:** true | false ---- - - ## interface MyConstraintType ```typescript @@ -162,19 +159,16 @@ interface InterfaceWithCall { (): { someProperty: T; } ``` -Type parameters: +**Type parameters:** | Name | | ---- | | T | -Return type: +**Return type:** { someProperty: T; } ---- - - ## interface InterfaceWithConstraintType ```typescript @@ -214,29 +208,24 @@ interface InterfaceWithMethod { someMethodOne(): T ``` -Return type: +**Return type:** T ---- - ```typescript someMethodTwo(): TReturn ``` -Type parameters: +**Type parameters:** | Name | | ------- | | TReturn | -Return type: +**Return type:** TReturn ---- - - ## interface Dictionary ```typescript @@ -258,12 +247,10 @@ interface Dictionary { new (): Dictionary ``` -Return type: +**Return type:** [Dictionary][InterfaceDeclaration-9]<TValue> ---- - ### Index signatures ```typescript @@ -274,9 +261,6 @@ Index `key` - string Type - TValue ---- - - ## interface MethodsInterface ```typescript @@ -292,43 +276,38 @@ interface MethodsInterface { (arg: TValue): void ``` -Type parameters: +**Type parameters:** | Name | | ------ | | TValue | -Parameters: +**Parameters:** | Name | Type | | ---- | ------ | | arg | TValue | -Return type: +**Return type:** void ---- - ### Methods ```typescript someMethod(): string ``` -Type parameters: +**Type parameters:** | Name | | ---- | | T | -Return type: +**Return type:** string ---- - - ## interface MonsterInterface Warning: Beta! @@ -345,7 +324,7 @@ interface MonsterInterface extends ObjectsInterface (key?: string | undefined): { someProperty: T; }; (key: number): { someProperty: T; }; readonly [key: string]: TValue; - readonly objectOne?: TValue; + readonly objectOne: TValue; objectTwo: TValue; } ``` @@ -366,96 +345,86 @@ interface MonsterInterface extends ObjectsInterface new (): MonsterInterface ``` -Type parameters: +**Type parameters:** | Name | | ---- | | T | -Return type: +**Return type:** [MonsterInterface][InterfaceDeclaration-12]<T> ---- - ```typescript new (someParameter: string): string ``` -Parameters: +**Parameters:** | Name | Type | | ------------- | ------ | | someParameter | string | -Return type: +**Return type:** string ---- - ### Call ```typescript (): { someProperty: T; } ``` -Type parameters: +**Type parameters:** | Name | | ---- | | T | -Return type: +**Return type:** { someProperty: T; } ---- - ```typescript (key?: string | undefined): { someProperty: T; } ``` -Type parameters: +**Type parameters:** | Name | | ---- | | T | -Parameters: +**Parameters:** | Name | Type | Optional | | ---- | ----------------------- | -------- | | key | undefined | string | Yes | -Return type: +**Return type:** { someProperty: T; } ---- - ```typescript (key: number): { someProperty: T; } ``` -Type parameters: +**Type parameters:** | Name | | ---- | | T | -Parameters: +**Parameters:** | Name | Type | | ---- | ------ | | key | number | -Return type: +**Return type:** { someProperty: T; } ---- - ### Index signatures ```typescript @@ -468,8 +437,6 @@ Index `key` - string Type - TValue ---- - ### Properties | Name | Type | @@ -496,8 +463,6 @@ Index `key` - string Type - string | number ---- - ```typescript [key: number]: string ``` @@ -506,9 +471,6 @@ Index `key` - number Type - string ---- - - ## interface StringsDictionary ```typescript @@ -527,9 +489,6 @@ Index `key` - string Type - string ---- - - ## interface MyInterface ```typescript diff --git a/packages/ts-docs-gen/src/file-manager.ts b/packages/ts-docs-gen/src/file-manager.ts index d5760681..60214a1c 100644 --- a/packages/ts-docs-gen/src/file-manager.ts +++ b/packages/ts-docs-gen/src/file-manager.ts @@ -14,6 +14,7 @@ interface OutputData { type RenderedItemList = Array; +// TODO: remove unused files before generating docs. export class FileManager { /** * diff --git a/packages/ts-docs-gen/src/plugins/api-callable-plugin.ts b/packages/ts-docs-gen/src/plugins/api-callable-plugin.ts index 73d144f8..0d77360b 100644 --- a/packages/ts-docs-gen/src/plugins/api-callable-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-callable-plugin.ts @@ -24,7 +24,6 @@ export class ApiCallablePlugin implements Plugin { parameters: Contracts.ApiParameterDto[], typeParameters: Contracts.ApiTypeParameterDto[] ): string { - switch (apiItem.ApiKind) { case Contracts.ApiItemKinds.Construct: { return GeneratorHelpers.ApiConstructToString(typeParameters, parameters, apiItem.ReturnType); @@ -58,7 +57,7 @@ export class ApiCallablePlugin implements Plugin { usedReferences.push(...table.References); builder - .Text("Type parameters:") + .Bold("Type parameters:") .EmptyLine() .Text(table.Text) .EmptyLine(); @@ -69,7 +68,7 @@ export class ApiCallablePlugin implements Plugin { usedReferences.push(...table.References); builder - .Text("Parameters:") + .Bold("Parameters:") .EmptyLine() .Text(table.Text) .EmptyLine(); @@ -79,7 +78,7 @@ export class ApiCallablePlugin implements Plugin { const renderedReturnType = GeneratorHelpers.TypeDtoToMarkdownString(data.ApiItem.ReturnType); builder - .Text("Return type:") + .Bold("Return type:") .EmptyLine() .Text(renderedReturnType.Text); diff --git a/packages/ts-docs-gen/src/plugins/api-interface-plugin.ts b/packages/ts-docs-gen/src/plugins/api-interface-plugin.ts index 9eb58f63..6bc8c1b1 100644 --- a/packages/ts-docs-gen/src/plugins/api-interface-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-interface-plugin.ts @@ -37,10 +37,10 @@ export class ApiInterfacePlugin implements Plugin { const typeParametersTable = GeneratorHelpers.ApiTypeParametersTableToString(typeParameters); const text = new MarkdownBuilder() + .EmptyLine() .Header("Type parameters", 3) .EmptyLine() .Text(typeParametersTable.Text) - .EmptyLine() .GetOutput(); return { @@ -56,18 +56,17 @@ export class ApiInterfacePlugin implements Plugin { } const builder = new MarkdownBuilder() - .Header("Extends", 3) - .EmptyLine(); + .EmptyLine() + .Header("Extends", 3); const references = []; for (const type of apiItem.Extends) { const typeDto = GeneratorHelpers.TypeDtoToMarkdownString(type); references.push(...typeDto.References); - builder - .Text(typeDto.Text) - .EmptyLine(); + .EmptyLine() + .Text(typeDto.Text); } return { @@ -88,6 +87,7 @@ export class ApiInterfacePlugin implements Plugin { const table = GeneratorHelpers.ApiPropertiesToTableString(apiItems); const builder = new MarkdownBuilder() + .EmptyLine() .Header("Properties", 3) .EmptyLine() .Text(table.Text); @@ -119,13 +119,13 @@ export class ApiInterfacePlugin implements Plugin { } const pluginResult = GeneratorHelpers.GetDefaultPluginResultData(); - pluginResult.Result.push(MarkdownGenerator.Header(title, 3), ""); + pluginResult.Result.push("", MarkdownGenerator.Header(title, 3)); for (const item of items) { + pluginResult.Result.push(""); const itemPluginResult = getPluginResult(item.Reference); GeneratorHelpers.MergePluginResultData(pluginResult, itemPluginResult); - pluginResult.Result.push("", MarkdownGenerator.HorizontalRule(), ""); } return pluginResult; @@ -133,6 +133,7 @@ export class ApiInterfacePlugin implements Plugin { public Render(data: PluginOptions): PluginResult { const alias = data.Reference.Alias; + const header = GeneratorHelpers.ApiInterfaceToSimpleString(alias, data.ApiItem); const pluginResult: PluginResult = { ...GeneratorHelpers.GetDefaultPluginResultData(), ApiItem: data.ApiItem, @@ -140,7 +141,7 @@ export class ApiInterfacePlugin implements Plugin { Headings: [ { ApiItemId: data.Reference.Id, - Heading: alias + Heading: header } ] }; @@ -153,11 +154,10 @@ export class ApiInterfacePlugin implements Plugin { const interfaceString = GeneratorHelpers.ApiInterfaceToString(data.ApiItem, data.ExtractedData); const builder = new MarkdownBuilder() - .Header(GeneratorHelpers.ApiInterfaceToSimpleString(alias, data.ApiItem), 2) + .Header(header, 2) .EmptyLine() .Text(GeneratorHelpers.RenderApiItemMetadata(data.ApiItem)) - .Code(interfaceString, GeneratorHelpers.DEFAULT_CODE_OPTIONS) - .EmptyLine(); + .Code(interfaceString, GeneratorHelpers.DEFAULT_CODE_OPTIONS); pluginResult.Result = builder.GetOutput(); diff --git a/packages/ts-docs-gen/tests/cases/__tests__/__snapshots__/simple-project-1.test.ts.snap b/packages/ts-docs-gen/tests/cases/__tests__/__snapshots__/simple-project-1.test.ts.snap index e19511ab..e28c11a5 100644 --- a/packages/ts-docs-gen/tests/cases/__tests__/__snapshots__/simple-project-1.test.ts.snap +++ b/packages/ts-docs-gen/tests/cases/__tests__/__snapshots__/simple-project-1.test.ts.snap @@ -5,13 +5,13 @@ Array [ Object { "FileLocation": "index.md", "Result": Array [ - "[InterfaceDeclaration-1]: index.md#foointerface", - "[InterfaceDeclaration-2]: index.md#boo", - "[InterfaceDeclaration-4]: index.md#myconstrainttype", - "[InterfaceDeclaration-9]: index.md#dictionary", - "[InterfaceDeclaration-9]: index.md#dictionary", - "[InterfaceDeclaration-6]: index.md#objectsinterface", - "[InterfaceDeclaration-12]: index.md#monsterinterface", + "[InterfaceDeclaration-1]: index.md#interface-foointerface", + "[InterfaceDeclaration-2]: index.md#interface-boo", + "[InterfaceDeclaration-4]: index.md#interface-myconstrainttype", + "[InterfaceDeclaration-9]: index.md#interface-dictionary", + "[InterfaceDeclaration-9]: index.md#interface-dictionary", + "[InterfaceDeclaration-6]: index.md#interface-objectsinterface", + "[InterfaceDeclaration-12]: index.md#interface-monsterinterface", "[ClassDeclaration-0]: index/foo.md#foo", "[ClassDeclaration-1]: index/world.md#world", "[ClassDeclaration-2]: index/earth.md#earth", @@ -91,26 +91,23 @@ Array [ "(param1: TValue, param2: TValue): boolean", "\`\`\`", "", - "Type parameters:", + "**Type parameters:**", "", "| Name |", "| ------ |", "| TValue |", "", - "Parameters:", + "**Parameters:**", "", "| Name | Type |", "| ------ | ------ |", "| param1 | TValue |", "| param2 | TValue |", "", - "Return type:", + "**Return type:**", "", "true | false", "", - "---", - "", - "", "## interface MyConstraintType", "", "\`\`\`typescript", @@ -173,19 +170,16 @@ Array [ "(): { someProperty: T; }", "\`\`\`", "", - "Type parameters:", + "**Type parameters:**", "", "| Name |", "| ---- |", "| T |", "", - "Return type:", + "**Return type:**", "", "{ someProperty: T; }", "", - "---", - "", - "", "## interface InterfaceWithConstraintType", "", "\`\`\`typescript", @@ -225,29 +219,24 @@ Array [ "someMethodOne(): T", "\`\`\`", "", - "Return type:", + "**Return type:**", "", "T", "", - "---", - "", "\`\`\`typescript", "someMethodTwo(): TReturn", "\`\`\`", "", - "Type parameters:", + "**Type parameters:**", "", "| Name |", "| ------- |", "| TReturn |", "", - "Return type:", + "**Return type:**", "", "TReturn", "", - "---", - "", - "", "## interface Dictionary", "", "\`\`\`typescript", @@ -269,12 +258,10 @@ Array [ "new (): Dictionary", "\`\`\`", "", - "Return type:", + "**Return type:**", "", "[Dictionary][InterfaceDeclaration-9]<TValue>", "", - "---", - "", "### Index signatures", "", "\`\`\`typescript", @@ -285,9 +272,6 @@ Array [ "", "Type - TValue", "", - "---", - "", - "", "## interface MethodsInterface", "", "\`\`\`typescript", @@ -303,43 +287,38 @@ Array [ "(arg: TValue): void", "\`\`\`", "", - "Type parameters:", + "**Type parameters:**", "", "| Name |", "| ------ |", "| TValue |", "", - "Parameters:", + "**Parameters:**", "", "| Name | Type |", "| ---- | ------ |", "| arg | TValue |", "", - "Return type:", + "**Return type:**", "", "void", "", - "---", - "", "### Methods", "", "\`\`\`typescript", "someMethod(): string", "\`\`\`", "", - "Type parameters:", + "**Type parameters:**", "", "| Name |", "| ---- |", "| T |", "", - "Return type:", + "**Return type:**", "", "string", "", - "---", - "", - "", "## interface MonsterInterface", "", "Warning: Beta!", @@ -377,96 +356,86 @@ Array [ "new (): MonsterInterface", "\`\`\`", "", - "Type parameters:", + "**Type parameters:**", "", "| Name |", "| ---- |", "| T |", "", - "Return type:", + "**Return type:**", "", "[MonsterInterface][InterfaceDeclaration-12]<T>", "", - "---", - "", "\`\`\`typescript", "new (someParameter: string): string", "\`\`\`", "", - "Parameters:", + "**Parameters:**", "", "| Name | Type |", "| ------------- | ------ |", "| someParameter | string |", "", - "Return type:", + "**Return type:**", "", "string", "", - "---", - "", "### Call", "", "\`\`\`typescript", "(): { someProperty: T; }", "\`\`\`", "", - "Type parameters:", + "**Type parameters:**", "", "| Name |", "| ---- |", "| T |", "", - "Return type:", + "**Return type:**", "", "{ someProperty: T; }", "", - "---", - "", "\`\`\`typescript", "(key?: string | undefined): { someProperty: T; }", "\`\`\`", "", - "Type parameters:", + "**Type parameters:**", "", "| Name |", "| ---- |", "| T |", "", - "Parameters:", + "**Parameters:**", "", "| Name | Type | Optional |", "| ---- | ----------------------- | -------- |", "| key | undefined | string | Yes |", "", - "Return type:", + "**Return type:**", "", "{ someProperty: T; }", "", - "---", - "", "\`\`\`typescript", "(key: number): { someProperty: T; }", "\`\`\`", "", - "Type parameters:", + "**Type parameters:**", "", "| Name |", "| ---- |", "| T |", "", - "Parameters:", + "**Parameters:**", "", "| Name | Type |", "| ---- | ------ |", "| key | number |", "", - "Return type:", + "**Return type:**", "", "{ someProperty: T; }", "", - "---", - "", "### Index signatures", "", "\`\`\`typescript", @@ -479,8 +448,6 @@ Array [ "", "Type - TValue", "", - "---", - "", "### Properties", "", "| Name | Type |", @@ -507,8 +474,6 @@ Array [ "", "Type - string | number", "", - "---", - "", "\`\`\`typescript", "[key: number]: string", "\`\`\`", @@ -517,9 +482,6 @@ Array [ "", "Type - string", "", - "---", - "", - "", "## interface StringsDictionary", "", "\`\`\`typescript", @@ -538,9 +500,6 @@ Array [ "", "Type - string", "", - "---", - "", - "", "## interface MyInterface", "", "\`\`\`typescript", diff --git a/packages/ts-docs-gen/tests/cases/simple-project-1/index.ts b/packages/ts-docs-gen/tests/cases/simple-project-1/index.ts index 14e297b0..4d7dd18d 100644 --- a/packages/ts-docs-gen/tests/cases/simple-project-1/index.ts +++ b/packages/ts-docs-gen/tests/cases/simple-project-1/index.ts @@ -88,7 +88,6 @@ export interface MyInterface { } // #endregion Interfaces - // #region Enums /** * Simple list.