diff --git a/packages/ts-docs-gen/examples/simple/docs/api/exported-functions.md b/packages/ts-docs-gen/examples/simple/docs/api/exported-functions.md index ac02df3f..a613767a 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/exported-functions.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/exported-functions.md @@ -1,24 +1,26 @@ # exported-functions -## Foo() +## Functions + +### Foo() ```typescript function Foo(): string ``` -### Return type +**Return type** string +---------- -## Bar() +### Bar() ```typescript function Bar(): string ``` -### Return type +**Return type** string - 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 e3b4a381..65aac989 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index.md @@ -1,14 +1,42 @@ -[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 +[InterfaceDeclaration-16]: index.md#props +[InterfaceDeclaration-16]: index.md#props +[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 [ClassDeclaration-0]: index/hello.md#hello # index -## interface ExtendedBar +## Functions + +### Component(arg) + +```typescript +function Component(arg: T): void +``` + +**Type parameters** + +| Name | Constraint type | Default type | +| ---- | -------------------------------- | -------------------------------- | +| T | [Props][InterfaceDeclaration-16] | [Props][InterfaceDeclaration-16] | + +**Parameters** + +| Name | Type | +| ---- | ---- | +| arg | T | + +**Return type** + +void + +## Interfaces + +### ExtendedBar ```typescript interface ExtendedBar extends Foo, Boo { @@ -16,19 +44,21 @@ interface ExtendedBar extends Foo, Boo { } ``` -### Extends +**Extends** [Foo][InterfaceDeclaration-1]<number> [Boo][InterfaceDeclaration-2] -### Properties +**Properties** | Name | Type | | ---------- | --------------------- | | OtherStuff | Array<string> | -## interface Foo +---------- + +### Foo ```typescript interface Foo { @@ -38,13 +68,13 @@ interface Foo { } ``` -### Type parameters +**Type parameters** | Name | | ----- | | TType | -### Properties +**Properties** | Name | Type | | ------- | ------ | @@ -52,7 +82,9 @@ interface Foo { | Surname | string | | Type | TType | -## interface Boo +---------- + +### Boo ```typescript interface Boo { @@ -60,13 +92,15 @@ interface Boo { } ``` -### Properties +**Properties** | Name | Type | | ---- | --------------------- | | Boos | Array<string> | -## interface AnotherInterface +---------- + +### AnotherInterface ```typescript interface AnotherInterface { @@ -74,30 +108,32 @@ interface AnotherInterface { } ``` -### Call +#### Call ```typescript (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 +---------- + +### MyConstraintType ```typescript interface MyConstraintType { @@ -105,13 +141,15 @@ interface MyConstraintType { } ``` -### Properties +**Properties** | Name | Type | | ---------- | ------ | | myProperty | string | -## interface MyDefaultType +---------- + +### MyDefaultType ```typescript interface MyDefaultType extends MyConstraintType { @@ -119,17 +157,19 @@ interface MyDefaultType extends MyConstraintType { } ``` -### Extends +**Extends** [MyConstraintType][InterfaceDeclaration-4] -### Properties +**Properties** | Name | Type | | --------------- | ------ | | anotherProperty | number | -## interface ObjectsInterface +---------- + +### ObjectsInterface ```typescript interface ObjectsInterface { @@ -138,14 +178,16 @@ interface ObjectsInterface { } ``` -### Properties +**Properties** | Name | Type | | --------- | ------ | | objectOne | Object | | objectTwo | Object | -## interface InterfaceWithCall +---------- + +### InterfaceWithCall ```typescript interface InterfaceWithCall { @@ -153,23 +195,25 @@ interface InterfaceWithCall { } ``` -### Call +#### Call ```typescript (): { someProperty: T; } ``` -**Type parameters:** +**Type parameters** | Name | | ---- | | T | -**Return type:** +**Return type** { someProperty: T; } -## interface InterfaceWithConstraintType +---------- + +### InterfaceWithConstraintType ```typescript interface InterfaceWithConstraintType extends Dictionary { @@ -177,17 +221,19 @@ interface InterfaceWithConstraintType extends Dictionary { } ``` -### Extends +**Extends** [Dictionary][InterfaceDeclaration-9]<string> -### Properties +**Properties** | Name | Type | | ------------ | ------ | | someProperty | string | -## interface InterfaceWithMethod +---------- + +### InterfaceWithMethod ```typescript interface InterfaceWithMethod { @@ -196,19 +242,19 @@ interface InterfaceWithMethod { } ``` -### Type parameters +**Type parameters** | Name | | ---- | | T | -### Methods +#### Methods ```typescript someMethodOne(): T ``` -**Return type:** +**Return type** T @@ -216,17 +262,19 @@ T someMethodTwo(): TReturn ``` -**Type parameters:** +**Type parameters** | Name | | ------- | | TReturn | -**Return type:** +**Return type** TReturn -## interface Dictionary +---------- + +### Dictionary ```typescript interface Dictionary { @@ -235,33 +283,34 @@ interface Dictionary { } ``` -### Type parameters +**Type parameters** | Name | | ------ | | TValue | -### Construct +#### Construct ```typescript new (): Dictionary ``` -**Return type:** +**Return type** [Dictionary][InterfaceDeclaration-9]<TValue> -### Index signatures +#### Index signatures ```typescript [key: string]: TValue ``` -Index `key` - string +* *Parameter* `key` - string +* *Type* TValue -Type - TValue +---------- -## interface MethodsInterface +### MethodsInterface ```typescript interface MethodsInterface { @@ -270,45 +319,47 @@ interface MethodsInterface { } ``` -### Call +#### Call ```typescript (arg: TValue): void ``` -**Type parameters:** +**Type parameters** | Name | | ------ | | TValue | -**Parameters:** +**Parameters** | Name | Type | | ---- | ------ | | arg | TValue | -**Return type:** +**Return type** void -### Methods +#### Methods ```typescript someMethod(): string ``` -**Type parameters:** +**Type parameters** | Name | | ---- | | T | -**Return type:** +**Return type** string -## interface MonsterInterface +---------- + +### MonsterInterface Warning: Beta! @@ -329,29 +380,29 @@ interface MonsterInterface extends ObjectsInterface } ``` -### Type parameters +**Type parameters** | Name | Constraint type | Default type | | ------ | --------------- | ------------ | -| TValue | Object | \{\} | +| TValue | Object | {} | -### Extends +**Extends** [ObjectsInterface][InterfaceDeclaration-6] -### Construct +#### Construct ```typescript new (): MonsterInterface ``` -**Type parameters:** +**Type parameters** | Name | | ---- | | T | -**Return type:** +**Return type** [MonsterInterface][InterfaceDeclaration-12]<T> @@ -359,29 +410,29 @@ new (): MonsterInterface new (someParameter: string): string ``` -**Parameters:** +**Parameters** | Name | Type | | ------------- | ------ | | someParameter | string | -**Return type:** +**Return type** string -### Call +#### Call ```typescript (): { someProperty: T; } ``` -**Type parameters:** +**Type parameters** | Name | | ---- | | T | -**Return type:** +**Return type** { someProperty: T; } @@ -389,19 +440,19 @@ string (key?: string | undefined): { someProperty: T; } ``` -**Type parameters:** +**Type parameters** | Name | | ---- | | T | -**Parameters:** +**Parameters** -| Name | Type | Optional | -| ---- | ----------------------- | -------- | -| key | undefined | string | Yes | +| Name | Type | +| ---- | ----------------------- | +| key | undefined | string | -**Return type:** +**Return type** { someProperty: T; } @@ -409,42 +460,41 @@ string (key: number): { someProperty: T; } ``` -**Type parameters:** +**Type parameters** | Name | | ---- | | T | -**Parameters:** +**Parameters** | Name | Type | | ---- | ------ | | key | number | -**Return type:** +**Return type** { someProperty: T; } -### Index signatures +#### Index signatures ```typescript readonly [key: string]: TValue ``` -Readonly. +* *Parameter* `key` - string +* *Type* TValue -Index `key` - string - -Type - TValue - -### Properties +**Properties** | Name | Type | | --------- | ------ | | objectOne | TValue | | objectTwo | TValue | -## interface SomeInterface +---------- + +### SomeInterface ```typescript interface SomeInterface { @@ -453,25 +503,25 @@ interface SomeInterface { } ``` -### Index signatures +#### Index signatures ```typescript [key: string]: string | number ``` -Index `key` - string - -Type - string | number +* *Parameter* `key` - string +* *Type* string | number ```typescript [key: number]: string ``` -Index `key` - number +* *Parameter* `key` - number +* *Type* string -Type - string +---------- -## interface StringsDictionary +### StringsDictionary ```typescript interface StringsDictionary { @@ -479,17 +529,18 @@ interface StringsDictionary { } ``` -### Index signatures +#### Index signatures ```typescript [key: string]: string ``` -Index `key` - string +* *Parameter* `key` - string +* *Type* string -Type - string +---------- -## interface MyInterface +### MyInterface ```typescript interface MyInterface { @@ -499,7 +550,7 @@ interface MyInterface { } ``` -### Properties +**Properties** | Name | Type | | --------------- | ------ | @@ -507,5 +558,75 @@ interface MyInterface { | MyPropertyTwo | Object | | MyPropertyThree | number | -## [Hello][ClassDeclaration-0] +---------- + +### Props + +```typescript +interface Props { + name: string; +} +``` + +**Properties** + +| Name | Type | +| ---- | ------ | +| name | string | + +## Enums + +### Uogos + +Warning: Beta! + +Deprecated! + +Some information +2nd line of some information +3rd line of some information +4th line of some information +5th line of some information + +> Some summary about this package version. + + +```typescript +enum Uogos { + Jokie = "jokie", + Braskes = "braskes" +} +``` + +**Members** + +| Name | Value | +| ------- | --------- | +| Jokie | "jokie" | +| Braskes | "braskes" | + +---------- + +### ConstSkaiciai + + +```typescript +const enum ConstSkaiciai { + PirmasC = 0, + AntrasC = 1, + TreciasC = 2 +} +``` + +**Members** + +| Name | Value | +| -------- | ----- | +| PirmasC | 0 | +| AntrasC | 1 | +| TreciasC | 2 | + +## Classes + +### [Hello][ClassDeclaration-0] diff --git a/packages/ts-docs-gen/examples/simple/docs/api/index/foonamespace.md b/packages/ts-docs-gen/examples/simple/docs/api/index/foonamespace.md index 71b8bf76..c1c32a0e 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index/foonamespace.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index/foonamespace.md @@ -1,5 +1,7 @@ -[ModuleDeclaration-1]: foonamespace\boonamespace.md#boonamespace +[ModuleDeclaration-1]: foonamespace/boonamespace.md#boonamespace # FooNamespace -## [BooNamespace][ModuleDeclaration-1] +## Namespaces + +### [BooNamespace][ModuleDeclaration-1] diff --git a/packages/ts-docs-gen/examples/simple/docs/api/index/foonamespace/boonamespace.md b/packages/ts-docs-gen/examples/simple/docs/api/index/foonamespace/boonamespace.md index 30f8cf31..3ea42f39 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index/foonamespace/boonamespace.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index/foonamespace/boonamespace.md @@ -1,5 +1,7 @@ -[ModuleDeclaration-2]: boonamespace\boonamespace2.md#boonamespace2 +[ModuleDeclaration-2]: boonamespace/boonamespace2.md#boonamespace2 # BooNamespace -## [BooNamespace2][ModuleDeclaration-2] +## Namespaces + +### [BooNamespace2][ModuleDeclaration-2] diff --git a/packages/ts-docs-gen/examples/simple/docs/api/index/foonamespace/boonamespace/boonamespace2.md b/packages/ts-docs-gen/examples/simple/docs/api/index/foonamespace/boonamespace/boonamespace2.md index 42007d6d..a6a1066b 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index/foonamespace/boonamespace/boonamespace2.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index/foonamespace/boonamespace/boonamespace2.md @@ -1,12 +1,14 @@ # BooNamespace2 -## Hello +## Variables + +### Hello ```typescript const Hello: "World!"; ``` -### Type +**Type** "World!" diff --git a/packages/ts-docs-gen/examples/simple/docs/api/index/hello.md b/packages/ts-docs-gen/examples/simple/docs/api/index/hello.md index 9c41c087..a7c0022e 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index/hello.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index/hello.md @@ -10,44 +10,40 @@ class Hello This is a constructor ```typescript -constructor(arg: string) +public constructor(arg: string) ``` -#### Parameters + +**Parameters** | Name | Type | Description | | ---- | ------ | ---------------------- | | arg | string | This is an argument ;) | +## Methods -## Properties - -### get Foo - -```typescript -public get Foo: string; -``` - -#### Type +### render(arg) -string +Warning: Beta! -### set Foo +Comment about Render ```typescript -public set Foo: string; +public render(arg: T): T ``` -#### Type +**Type parameters** -string +| Name | Constraint type | Default type | +| ---- | --------------- | ------------ | +| T | String | String | -### set Bar +**Parameters** -```typescript -public static set Bar: string; -``` +| Name | Type | Description | +| ---- | ---- | ---------------------- | +| arg | T | Argument comment here. | -#### Type +**Return type** -string +T diff --git a/packages/ts-docs-gen/examples/simple/index.ts b/packages/ts-docs-gen/examples/simple/index.ts index 80ef5a90..f3ac7c21 100644 --- a/packages/ts-docs-gen/examples/simple/index.ts +++ b/packages/ts-docs-gen/examples/simple/index.ts @@ -198,21 +198,21 @@ export interface MyInterface { // export const name = "some-kind-of-module"; // } -// /** -// * Some information -// * 2nd line of some information -// * 3rd line of some information -// * 4th line of some information -// * 5th line of some information -// * @summary Some summary about this package version. -// * @summary 2nd of some summary about this package version. -// * @deprecated -// * @beta -// */ -// export enum Uogos { -// Jokie = "jokie", -// Braskes = "braskes" -// } +/** + * Some information + * 2nd line of some information + * 3rd line of some information + * 4th line of some information + * 5th line of some information + * @summary Some summary about this package version. + * @summary 2nd of some summary about this package version. + * @deprecated + * @beta + */ +export enum Uogos { + Jokie = "jokie", + Braskes = "braskes" +} // export enum Skaiciai { // Nulis = 0, @@ -235,11 +235,11 @@ export interface MyInterface { // Trecias // } -// export const enum ConstSkaiciai { -// PirmasC = 0, -// AntrasC = 1, -// TreciasC = 2 -// } +export const enum ConstSkaiciai { + PirmasC = 0, + AntrasC = 1, + TreciasC = 2 +} // export const enum ConstSarasas { // /** @@ -292,13 +292,11 @@ export interface MyInterface { // */ // export type Hello = Uogos; -// export namespace FooNamespace { -// export namespace BooNamespace { -// export namespace BooNamespace2 { -// export const Hello = "World!"; -// } -// } -// } +export interface Props { + name: string; +} + +export function Component(arg: T): void { } export class Hello { /** @@ -307,11 +305,20 @@ export class Hello { */ constructor(arg: string) { } - get Foo(): string { - throw new Error("Method not implemented."); + /** + * Comment about Render + * @beta + * @param arg Argument comment here. + */ + public render(arg: T): T { + return arg; } - set Foo(arg: string) { } + // get Foo(): string { + // throw new Error("Method not implemented."); + // } + + // set Foo(arg: string) { } - public static set Bar(arg: string) { } + // public static set Bar(arg: string) { } } diff --git a/packages/ts-docs-gen/src/abstractions/base-plugin.ts b/packages/ts-docs-gen/src/abstractions/base-plugin.ts new file mode 100644 index 00000000..bbfaebb8 --- /dev/null +++ b/packages/ts-docs-gen/src/abstractions/base-plugin.ts @@ -0,0 +1,83 @@ +import { Contracts } from "ts-extractor"; +import { MarkdownBuilder } from "@simplrjs/markdown"; + +import { Plugin, SupportedApiItemKindType, PluginOptions, PluginResult, PluginResultData } from "../contracts/plugin"; +import { GeneratorHelpers } from "../generator-helpers"; + +export abstract class BasePlugin implements Plugin { + public abstract SupportedApiItemKinds(): SupportedApiItemKindType[]; + + public CheckApiItem(item: TKind): boolean { + return true; + } + + // TODO: Escape string! + protected RenderTypeParameters(typeParameters: Contracts.ApiTypeParameterDto[]): PluginResultData | undefined { + if (typeParameters.length === 0) { + return undefined; + } + + const pluginResult = GeneratorHelpers.GetDefaultPluginResultData(); + const header = ["Name", "Constraint type", "Default type"]; + + const content = typeParameters.map(typeParameter => { + // ConstraintType + let constraintType: GeneratorHelpers.TypeToStringDto; + if (typeParameter.ConstraintType != null) { + constraintType = GeneratorHelpers.TypeDtoToMarkdownString(typeParameter.ConstraintType); + GeneratorHelpers.MergePluginResultData(pluginResult, { + UsedReferences: constraintType.References + }); + } else { + constraintType = { References: [], Text: "" }; + } + + // DefaultType + let defaultType: GeneratorHelpers.TypeToStringDto; + if (typeParameter.DefaultType != null) { + defaultType = GeneratorHelpers.TypeDtoToMarkdownString(typeParameter.DefaultType); + GeneratorHelpers.MergePluginResultData(pluginResult, { + UsedReferences: defaultType.References + }); + } else { + defaultType = { References: [], Text: "" }; + } + + return [ + typeParameter.Name, + constraintType.Text, + defaultType.Text + ]; + }); + + pluginResult.Result = new MarkdownBuilder() + .EmptyLine() + .Bold("Type parameters") + .EmptyLine() + .Table(header, content, GeneratorHelpers.DEFAULT_TABLE_OPTIONS) + .GetOutput(); + + return pluginResult; + } + + protected RenderType(type?: Contracts.TypeDto): PluginResultData | undefined { + if (type == null) { + return undefined; + } + const pluginResult = GeneratorHelpers.GetDefaultPluginResultData(); + + const parsedReturnType = GeneratorHelpers.TypeDtoToMarkdownString(type); + + pluginResult.Result = new MarkdownBuilder() + .EmptyLine() + .Bold("Type") + .EmptyLine() + .Text(parsedReturnType.Text) + .GetOutput(); + + pluginResult.UsedReferences = parsedReturnType.References; + return pluginResult; + } + + public abstract Render(data: PluginOptions): PluginResult; +} diff --git a/packages/ts-docs-gen/src/abstractions/container-plugin.ts b/packages/ts-docs-gen/src/abstractions/container-plugin.ts new file mode 100644 index 00000000..b4efafab --- /dev/null +++ b/packages/ts-docs-gen/src/abstractions/container-plugin.ts @@ -0,0 +1,115 @@ +import { Contracts, ExtractDto } from "ts-extractor"; +import { MarkdownBuilder } from "@simplrjs/markdown"; +import { BasePlugin } from "./base-plugin"; +import { PluginOptions, PluginResultData } from "../contracts/plugin"; +import { GeneratorHelpers } from "../generator-helpers"; +import { ApiItemReference } from "../contracts/api-item-reference"; + +export interface ApiContainer extends Contracts.ApiBaseItemDto { + Members: Contracts.ApiItemReference[]; +} + +export interface ContainerMembersKindsGroup { + Heading: string; + Kinds: Contracts.ApiItemKinds[]; +} + +interface ContainerMembersReferencesGroup { + Heading: string; + References: ApiItemReference[]; +} + +export abstract class ContainerPlugin extends BasePlugin { + private getItemsReferenceByKind( + list: ContainerMembersKindsGroup[], + members: Contracts.ApiItemReference[], + extractedData: ExtractDto + ): ContainerMembersReferencesGroup[] { + const result: ContainerMembersReferencesGroup[] = []; + let membersReferences = GeneratorHelpers.GetApiItemReferences(extractedData, members); + + for (const item of list) { + // Filter item references by kind + const apiItemsReferenceByKind = membersReferences.filter(x => item.Kinds.indexOf(extractedData.Registry[x.Id].ApiKind) !== -1); + // Remove references that was used + membersReferences = membersReferences.filter(x => apiItemsReferenceByKind.indexOf(x) === -1); + + result.push({ + Heading: item.Heading, + References: apiItemsReferenceByKind + }); + } + + // TODO: Using ApiKind.Any to add everything to other if some kind is not supported. + if (membersReferences.length !== 0) { + result.push({ + Heading: "Other", + References: membersReferences + }); + } + + return result; + } + + protected RenderMembersGroups(list: ContainerMembersKindsGroup[], options: PluginOptions): PluginResultData { + const membersReferences = this.getItemsReferenceByKind(list, options.ApiItem.Members, options.ExtractedData); + const pluginResultData = GeneratorHelpers.GetDefaultPluginResultData(); + const builder = new MarkdownBuilder(); + + for (const { Heading, References } of membersReferences) { + if (References.length > 0) { + builder + .Header(Heading, 2) + .EmptyLine(); + + for (const reference of References) { + const apiItem = options.ExtractedData.Registry[reference.Id]; + + if (options.IsPluginResultExists(reference)) { + builder + .Text(md => md.Header(md.Link(apiItem.Name, reference.Id, true), 3)) + .EmptyLine(); + pluginResultData.UsedReferences.push(reference.Id); + } else { + switch (apiItem.ApiKind) { + case Contracts.ApiItemKinds.Namespace: + case Contracts.ApiItemKinds.Class: { + const renderedItem = options.GetItemPluginResult(reference); + pluginResultData.Members.push({ + Reference: reference, + PluginResult: renderedItem + }); + + builder + .Text(md => md.Header(md.Link(renderedItem.ApiItem.Name, reference.Id, true), 3)) + .EmptyLine(); + pluginResultData.UsedReferences.push(reference.Id); + break; + } + default: { + const renderedItem = options.GetItemPluginResult(reference); + builder + .Text(renderedItem.Result) + .EmptyLine(); + + GeneratorHelpers.MergePluginResultData(pluginResultData, { + Headings: renderedItem.Headings, + UsedReferences: renderedItem.UsedReferences + }); + } + } + } + + if ((References.indexOf(reference) + 1) !== References.length) { + builder + .HorizontalRule(undefined, 10) + .EmptyLine(); + } + } + } + } + + pluginResultData.Result = builder.GetOutput(); + return pluginResultData; + } +} diff --git a/packages/ts-docs-gen/src/abstractions/function-like-plugin.ts b/packages/ts-docs-gen/src/abstractions/function-like-plugin.ts new file mode 100644 index 00000000..0266acee --- /dev/null +++ b/packages/ts-docs-gen/src/abstractions/function-like-plugin.ts @@ -0,0 +1,55 @@ +import { Contracts } from "ts-extractor"; +import { MarkdownGenerator, MarkdownBuilder } from "@simplrjs/markdown"; + +import { BasePlugin } from "./base-plugin"; +import { PluginResultData } from "../contracts/plugin"; +import { GeneratorHelpers } from "../generator-helpers"; + +export abstract class FunctionLikePlugin extends BasePlugin { + // TODO: Escape string! + protected RenderParameters(parameters: Contracts.ApiParameterDto[]): PluginResultData | undefined { + if (parameters.length === 0) { + return undefined; + } + + const pluginResult = GeneratorHelpers.GetDefaultPluginResultData(); + const header = ["Name", "Type", "Description"]; + + const content = parameters.map(parameter => { + const parameterTypeDto = GeneratorHelpers.TypeDtoToMarkdownString(parameter.Type); + GeneratorHelpers.MergePluginResultData(pluginResult, { + UsedReferences: parameterTypeDto.References + }); + + return [parameter.Name, MarkdownGenerator.EscapeString(parameterTypeDto.Text), parameter.Metadata.DocumentationComment]; + }); + + pluginResult.Result = new MarkdownBuilder() + .EmptyLine() + .Bold("Parameters") + .EmptyLine() + .Table(header, content, GeneratorHelpers.DEFAULT_TABLE_OPTIONS) + .GetOutput(); + + return pluginResult; + } + + protected RenderReturnType(type?: Contracts.TypeDto): PluginResultData | undefined { + if (type == null) { + return undefined; + } + const pluginResult = GeneratorHelpers.GetDefaultPluginResultData(); + + const parsedReturnType = GeneratorHelpers.TypeDtoToMarkdownString(type); + + pluginResult.Result = new MarkdownBuilder() + .EmptyLine() + .Bold("Return type") + .EmptyLine() + .Text(parsedReturnType.Text) + .GetOutput(); + + pluginResult.UsedReferences = parsedReturnType.References; + return pluginResult; + } +} diff --git a/packages/ts-docs-gen/src/contracts/plugin.ts b/packages/ts-docs-gen/src/contracts/plugin.ts index b35399db..1b6b4df3 100644 --- a/packages/ts-docs-gen/src/contracts/plugin.ts +++ b/packages/ts-docs-gen/src/contracts/plugin.ts @@ -42,7 +42,7 @@ export interface PluginResultData { * Plugin rendered result. */ Result: string[]; - Members?: PluginMember[]; + Members: PluginMember[]; } export interface PluginResult extends PluginResultData { diff --git a/packages/ts-docs-gen/src/generator-helpers.ts b/packages/ts-docs-gen/src/generator-helpers.ts index 5da4cfbb..562fed93 100644 --- a/packages/ts-docs-gen/src/generator-helpers.ts +++ b/packages/ts-docs-gen/src/generator-helpers.ts @@ -19,6 +19,7 @@ export namespace GeneratorHelpers { export enum JSDocTags { Beta = "beta", Deprecated = "deprecated", + Internal = "internal", Summary = "summary" } @@ -160,7 +161,8 @@ export namespace GeneratorHelpers { return { Headings: [], Result: [], - UsedReferences: [] + UsedReferences: [], + Members: [] }; } // #endregion General helpers @@ -233,6 +235,7 @@ export namespace GeneratorHelpers { // Optimise? const isBeta = apiItem.Metadata.JSDocTags.findIndex(x => x.name.toLowerCase() === JSDocTags.Beta) !== -1; const deprecated = apiItem.Metadata.JSDocTags.find(x => x.name.toLowerCase() === JSDocTags.Deprecated); + const internal = apiItem.Metadata.JSDocTags.find(x => x.name.toLowerCase() === JSDocTags.Internal); const summary = apiItem.Metadata.JSDocTags.find(x => x.name.toLowerCase() === JSDocTags.Summary); const jSDocComment = apiItem.Metadata.DocumentationComment; @@ -249,6 +252,13 @@ export namespace GeneratorHelpers { .EmptyLine(); } + if (internal != null) { + const message = Boolean(internal.text) ? `: ${internal.text}` : ""; + builder + .Bold(`Internal${message}`) + .EmptyLine(); + } + if (jSDocComment.length > 0) { builder .Text(jSDocComment) @@ -429,7 +439,10 @@ export namespace GeneratorHelpers { return `${apiItem.AccessModifier}${$static}${abstract}${readOnly} ${name}${optional}: ${apiItem.Type.Text};`; } - export function EnumToString(alias: string, memberItems: Contracts.ApiEnumMemberDto[]): string[] { + export function ApiEnumToString(apiItem: Contracts.ApiEnumDto, memberItems: Contracts.ApiEnumMemberDto[], alias?: string): string[] { + const name = alias || apiItem.Name; + const $const = apiItem.IsConst ? "const " : ""; + // Constructing enum body. const membersStrings = memberItems.map((memberItem, index, array) => { // Add an enum name @@ -450,7 +463,7 @@ export namespace GeneratorHelpers { // Construct enum code output return [ - `enum ${alias} {`, + `${$const}enum ${name} {`, ...membersStrings, "}" ]; @@ -642,9 +655,13 @@ export namespace GeneratorHelpers { return `${apiItem.Name}${isOptionalString}: ${apiItem.Type.Text}${initializerString}`; } - export function ApiClassConstructorToString(parameters?: Contracts.ApiParameterDto[], returnType?: Contracts.TypeDto): string { + export function ApiClassConstructorToString( + apiItem: Contracts.ApiClassConstructorDto, + parameters?: Contracts.ApiParameterDto[], + returnType?: Contracts.TypeDto + ): string { const callString = ApiCallToString(undefined, parameters, returnType); - return `constructor${callString}`; + return `${apiItem.AccessModifier} constructor${callString}`; } /** 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 0d77360b..6075f2d9 100644 --- a/packages/ts-docs-gen/src/plugins/api-callable-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-callable-plugin.ts @@ -1,12 +1,13 @@ import { Contracts } from "ts-extractor"; import { MarkdownBuilder } from "@simplrjs/markdown"; -import { Plugin, SupportedApiItemKindType, PluginResult, PluginOptions } from "../contracts/plugin"; +import { SupportedApiItemKindType, PluginResult, PluginOptions } from "../contracts/plugin"; import { GeneratorHelpers } from "../generator-helpers"; +import { FunctionLikePlugin } from "../abstractions/function-like-plugin"; export type CallableApiItem = Contracts.ApiCallDto | Contracts.ApiMethodDto | Contracts.ApiConstructDto; -export class ApiCallablePlugin implements Plugin { +export class ApiCallablePlugin extends FunctionLikePlugin { public SupportedApiItemKinds(): SupportedApiItemKindType[] { return [ GeneratorHelpers.ApiItemKinds.Construct, @@ -15,10 +16,6 @@ export class ApiCallablePlugin implements Plugin { ]; } - public CheckApiItem(item: CallableApiItem): boolean { - return true; - } - private resolveItemCode( apiItem: CallableApiItem, parameters: Contracts.ApiParameterDto[], @@ -37,60 +34,36 @@ export class ApiCallablePlugin implements Plugin { } } - public Render(data: PluginOptions): PluginResult { - const usedReferences = []; - const parameters = GeneratorHelpers.GetApiItemsFromReference( - data.ApiItem.Parameters, - data.ExtractedData - ); - const typeParameters = GeneratorHelpers.GetApiItemsFromReference( - data.ApiItem.TypeParameters, - data.ExtractedData - ); - - const builder = new MarkdownBuilder() - .Code(this.resolveItemCode(data.ApiItem, parameters, typeParameters), GeneratorHelpers.DEFAULT_CODE_OPTIONS) - .EmptyLine(); - - if (typeParameters.length > 0) { - const table = GeneratorHelpers.ApiTypeParametersTableToString(typeParameters); - usedReferences.push(...table.References); - - builder - .Bold("Type parameters:") - .EmptyLine() - .Text(table.Text) - .EmptyLine(); - } + public Render(options: PluginOptions): PluginResult { + const pluginResult: PluginResult = { + ...GeneratorHelpers.GetDefaultPluginResultData(), + ApiItem: options.ApiItem, + Reference: options.Reference + }; - if (parameters.length > 0) { - const table = GeneratorHelpers.ApiParametersToTableString(parameters); - usedReferences.push(...table.References); + // ApiParameters + const apiParameters = + GeneratorHelpers.GetApiItemsFromReference(options.ApiItem.Parameters, options.ExtractedData); + // ApiTypeParameters + const apiTypeParameters = + GeneratorHelpers.GetApiItemsFromReference(options.ApiItem.TypeParameters, options.ExtractedData); - builder - .Bold("Parameters:") - .EmptyLine() - .Text(table.Text) - .EmptyLine(); - } + pluginResult.Result = new MarkdownBuilder() + .Code(this.resolveItemCode(options.ApiItem, apiParameters, apiTypeParameters), GeneratorHelpers.DEFAULT_CODE_OPTIONS) + .GetOutput(); - if (data.ApiItem.ReturnType) { - const renderedReturnType = GeneratorHelpers.TypeDtoToMarkdownString(data.ApiItem.ReturnType); + // TypeParameters + const typeParametersResult = this.RenderTypeParameters(apiTypeParameters); + GeneratorHelpers.MergePluginResultData(pluginResult, typeParametersResult); - builder - .Bold("Return type:") - .EmptyLine() - .Text(renderedReturnType.Text); + // Parameters + const parametersResult = this.RenderParameters(apiParameters); + GeneratorHelpers.MergePluginResultData(pluginResult, parametersResult); - usedReferences.push(...renderedReturnType.References); - } + // ReturnType + const returnTypeResult = this.RenderReturnType(options.ApiItem.ReturnType); + GeneratorHelpers.MergePluginResultData(pluginResult, returnTypeResult); - return { - ApiItem: data.ApiItem, - Reference: data.Reference, - Headings: [], - Result: builder.GetOutput(), - UsedReferences: usedReferences - }; + return pluginResult; } } diff --git a/packages/ts-docs-gen/src/plugins/api-class-accessor-plugin.ts b/packages/ts-docs-gen/src/plugins/api-class-accessor-plugin.ts index 6974fc7d..607b3437 100644 --- a/packages/ts-docs-gen/src/plugins/api-class-accessor-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-class-accessor-plugin.ts @@ -1,11 +1,13 @@ import { Contracts, ExtractDto } from "ts-extractor"; -import { Plugin, SupportedApiItemKindType, PluginOptions, PluginResult, PluginResultData } from "../contracts/plugin"; -import { GeneratorHelpers } from "../generator-helpers"; import { MarkdownBuilder } from "@simplrjs/markdown"; +import { SupportedApiItemKindType, PluginOptions, PluginResult } from "../contracts/plugin"; +import { GeneratorHelpers } from "../generator-helpers"; +import { BasePlugin } from "../abstractions/base-plugin"; + export type Kind = Contracts.ApiSetAccessorDto | Contracts.ApiGetAccessorDto; -export class ApiClassAccessorPlugin implements Plugin { +export class ApiClassAccessorPlugin extends BasePlugin { public SupportedApiItemKinds(): SupportedApiItemKindType[] { return [ GeneratorHelpers.ApiItemKinds.GetAccessor, @@ -13,10 +15,6 @@ export class ApiClassAccessorPlugin implements Plugin { ]; } - public CheckApiItem(item: Kind): boolean { - return true; - } - private getHeading(data: PluginOptions): string { let accessorType: string; if (data.ApiItem.ApiKind === Contracts.ApiItemKinds.SetAccessor) { @@ -29,11 +27,14 @@ export class ApiClassAccessorPlugin implements Plugin { } private resolveType(apiItem: Kind, extractedData: ExtractDto): Contracts.TypeDto | undefined { - // Resolve type let type: Contracts.TypeDto | undefined; if (apiItem.ApiKind === Contracts.ApiItemKinds.GetAccessor) { + // GetAccessor + type = apiItem.Type; } else if (apiItem.Parameter != null) { + // SetAccessor + const apiParameter = extractedData.Registry[apiItem.Parameter.Ids[0]] as Contracts.ApiParameterDto; if (apiParameter != null) { type = apiParameter.Type; @@ -43,49 +44,35 @@ export class ApiClassAccessorPlugin implements Plugin { return type; } - private renderTypeDto(type: Contracts.TypeDto | undefined): Partial | undefined { - if (type == null) { - return undefined; - } - - const result = GeneratorHelpers.TypeDtoToMarkdownString(type); - - const builder = new MarkdownBuilder() - .EmptyLine() - .Header("Type", 4) - .EmptyLine() - .Text(result.Text); - - return { - Result: builder.GetOutput(), - UsedReferences: result.References - }; - } - - public Render(data: PluginOptions): PluginResult { - const heading = this.getHeading(data); - const type = this.resolveType(data.ApiItem, data.ExtractedData); + public Render(options: PluginOptions): PluginResult { + const heading = this.getHeading(options); + const type = this.resolveType(options.ApiItem, options.ExtractedData); const pluginResult: PluginResult = { ...GeneratorHelpers.GetDefaultPluginResultData(), - ApiItem: data.ApiItem, - Reference: data.Reference, + ApiItem: options.ApiItem, + Reference: options.Reference, Headings: [ { - ApiItemId: data.Reference.Id, + ApiItemId: options.Reference.Id, Heading: heading } ] }; + // Header pluginResult.Result = new MarkdownBuilder() .Header(heading, 3) .EmptyLine() - .Text(GeneratorHelpers.RenderApiItemMetadata(data.ApiItem)) - .Code(GeneratorHelpers.ApiAccessorToString(data.ApiItem, type, data.Reference.Alias), GeneratorHelpers.DEFAULT_CODE_OPTIONS) + .Text(GeneratorHelpers.RenderApiItemMetadata(options.ApiItem)) + .Code(GeneratorHelpers.ApiAccessorToString( + options.ApiItem, + type, + options.Reference.Alias + ), GeneratorHelpers.DEFAULT_CODE_OPTIONS) .GetOutput(); // Type - const typeResult = this.renderTypeDto(type); + const typeResult = this.RenderType(type); GeneratorHelpers.MergePluginResultData(pluginResult, typeResult); return pluginResult; diff --git a/packages/ts-docs-gen/src/plugins/api-class-constructor-plugin.ts b/packages/ts-docs-gen/src/plugins/api-class-constructor-plugin.ts index c2d3680e..f90ef37d 100644 --- a/packages/ts-docs-gen/src/plugins/api-class-constructor-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-class-constructor-plugin.ts @@ -1,73 +1,45 @@ import { Contracts } from "ts-extractor"; -import { MarkdownBuilder, MarkdownGenerator } from "@simplrjs/markdown"; -import { Plugin, SupportedApiItemKindType, PluginOptions, PluginResult, PluginResultData } from "../contracts/plugin"; +import { MarkdownBuilder } from "@simplrjs/markdown"; + +import { SupportedApiItemKindType, PluginOptions, PluginResult } from "../contracts/plugin"; import { GeneratorHelpers } from "../generator-helpers"; +import { FunctionLikePlugin } from "../abstractions/function-like-plugin"; -export class ApiClassConstructorPlugin implements Plugin { +export class ApiClassConstructorPlugin extends FunctionLikePlugin { public SupportedApiItemKinds(): SupportedApiItemKindType[] { return [GeneratorHelpers.ApiItemKinds.ClassConstructor]; } - public CheckApiItem(item: Contracts.ApiItemDto): boolean { - return true; - } - - private renderParameters(parameters: Contracts.ApiParameterDto[]): PluginResultData { - const pluginResult = GeneratorHelpers.GetDefaultPluginResultData(); - if (parameters.length === 0) { - return pluginResult; - } - - let referenceIds: string[] = []; - const header = ["Name", "Type", "Description"]; - - const content = parameters.map(parameter => { - const parameterTypeDto = GeneratorHelpers.TypeDtoToMarkdownString(parameter.Type); - - referenceIds = referenceIds.concat(parameterTypeDto.References); - - return [parameter.Name, MarkdownGenerator.EscapeString(parameterTypeDto.Text), parameter.Metadata.DocumentationComment]; - }); - - const builder = new MarkdownBuilder() - .Header("Parameters", 4) - .EmptyLine() - .Table(header, content, GeneratorHelpers.DEFAULT_TABLE_OPTIONS) - .EmptyLine(); - - pluginResult.UsedReferences = referenceIds; - pluginResult.Result = builder.GetOutput(); - - return pluginResult; - } - public Render(options: PluginOptions): PluginResult { - const pluginResult = GeneratorHelpers.GetDefaultPluginResultData(); - const builder = new MarkdownBuilder(); - - // Parameters + // ApiParameters const apiParameters = GeneratorHelpers .GetApiItemsFromReference(options.ApiItem.Parameters, options.ExtractedData); - const parameters = this.renderParameters(apiParameters); const heading = GeneratorHelpers.MethodToSimpleString("constructor", apiParameters); + const pluginResult: PluginResult = { + ...GeneratorHelpers.GetDefaultPluginResultData(), + ApiItem: options.ApiItem, + Reference: options.Reference, + Headings: [ + { + Heading: heading, + ApiItemId: options.Reference.Id + } + ] + }; - pluginResult.Headings.push({ ApiItemId: options.Reference.Id, Heading: heading }); - - builder + // Header + pluginResult.Result = new MarkdownBuilder() .Header(heading, 3) .EmptyLine() .Text(GeneratorHelpers.RenderApiItemMetadata(options.ApiItem)) - .Code(GeneratorHelpers.ApiClassConstructorToString(apiParameters), GeneratorHelpers.DEFAULT_CODE_OPTIONS) - .Text(parameters.Result); + .Code(GeneratorHelpers.ApiClassConstructorToString(options.ApiItem, apiParameters), GeneratorHelpers.DEFAULT_CODE_OPTIONS) + .GetOutput(); - GeneratorHelpers.MergePluginResultData(pluginResult, parameters); - pluginResult.Result = builder.GetOutput(); + // Parameters + const parametersResult = this.RenderParameters(apiParameters); + GeneratorHelpers.MergePluginResultData(pluginResult, parametersResult); - return { - ApiItem: options.ApiItem, - Reference: options.Reference, - ...pluginResult - }; + return pluginResult; } } diff --git a/packages/ts-docs-gen/src/plugins/api-class-method-plugin.ts b/packages/ts-docs-gen/src/plugins/api-class-method-plugin.ts index ea1759a7..5da07cf0 100644 --- a/packages/ts-docs-gen/src/plugins/api-class-method-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-class-method-plugin.ts @@ -1,9 +1,11 @@ import { Contracts } from "ts-extractor"; -import { MarkdownBuilder, MarkdownGenerator } from "@simplrjs/markdown"; -import { Plugin, SupportedApiItemKindType, PluginOptions, PluginResult, PluginResultData } from "../contracts/plugin"; +import { MarkdownBuilder } from "@simplrjs/markdown"; + +import { SupportedApiItemKindType, PluginOptions, PluginResult } from "../contracts/plugin"; import { GeneratorHelpers } from "../generator-helpers"; +import { FunctionLikePlugin } from "../abstractions/function-like-plugin"; -export class ApiClassMethodPlugin implements Plugin { +export class ApiClassMethodPlugin extends FunctionLikePlugin { public SupportedApiItemKinds(): SupportedApiItemKindType[] { return [GeneratorHelpers.ApiItemKinds.ClassMethod]; } @@ -12,53 +14,29 @@ export class ApiClassMethodPlugin implements Plugin return true; } - private renderParameters(parameters: Contracts.ApiParameterDto[]): PluginResultData { - const pluginResult = GeneratorHelpers.GetDefaultPluginResultData(); - if (parameters.length === 0) { - return pluginResult; - } - - let referenceIds: string[] = []; - const header = ["Name", "Type", "Description"]; - - const content = parameters.map(parameter => { - const parameterTypeDto = GeneratorHelpers.TypeDtoToMarkdownString(parameter.Type); - - referenceIds = referenceIds.concat(parameterTypeDto.References); - - return [parameter.Name, MarkdownGenerator.EscapeString(parameterTypeDto.Text), parameter.Metadata.DocumentationComment]; - }); - - const builder = new MarkdownBuilder() - .Header("Parameters", 4) - .EmptyLine() - .Table(header, content, GeneratorHelpers.DEFAULT_TABLE_OPTIONS) - .EmptyLine(); - - pluginResult.UsedReferences = referenceIds; - pluginResult.Result = builder.GetOutput(); - - return pluginResult; - } - public Render(options: PluginOptions): PluginResult { - const pluginResult = GeneratorHelpers.GetDefaultPluginResultData(); - const builder = new MarkdownBuilder(); - // Parameters const apiParameters = GeneratorHelpers .GetApiItemsFromReference(options.ApiItem.Parameters, options.ExtractedData); - const parameters = this.renderParameters(apiParameters); - - // Parameters + // TypeParameters const apiTypeParameters = GeneratorHelpers .GetApiItemsFromReference(options.ApiItem.TypeParameters, options.ExtractedData); const heading = GeneratorHelpers.MethodToSimpleString(options.Reference.Alias, apiParameters); + const pluginResult: PluginResult = { + ...GeneratorHelpers.GetDefaultPluginResultData(), + ApiItem: options.ApiItem, + Reference: options.Reference, + Headings: [ + { + Heading: heading, + ApiItemId: options.Reference.Id + } + ] + }; - pluginResult.Headings.push({ ApiItemId: options.Reference.Id, Heading: heading }); - - builder + // Header + pluginResult.Result = new MarkdownBuilder() .Header(heading, 3) .EmptyLine() .Text(GeneratorHelpers.RenderApiItemMetadata(options.ApiItem)) @@ -68,15 +46,20 @@ export class ApiClassMethodPlugin implements Plugin apiParameters, options.Reference.Alias ), GeneratorHelpers.DEFAULT_CODE_OPTIONS) - .Text(parameters.Result); + .GetOutput(); - GeneratorHelpers.MergePluginResultData(pluginResult, parameters); - pluginResult.Result = builder.GetOutput(); + // TypeParameters + const typeParametersResult = this.RenderTypeParameters(apiTypeParameters); + GeneratorHelpers.MergePluginResultData(pluginResult, typeParametersResult); - return { - ApiItem: options.ApiItem, - Reference: options.Reference, - ...pluginResult - }; + // Parameters + const parametersResult = this.RenderParameters(apiParameters); + GeneratorHelpers.MergePluginResultData(pluginResult, parametersResult); + + // ReturnType + const returnTypeResult = this.RenderReturnType(options.ApiItem.ReturnType); + GeneratorHelpers.MergePluginResultData(pluginResult, returnTypeResult); + + return pluginResult; } } diff --git a/packages/ts-docs-gen/src/plugins/api-class-plugin.ts b/packages/ts-docs-gen/src/plugins/api-class-plugin.ts index e4b96580..443c0227 100644 --- a/packages/ts-docs-gen/src/plugins/api-class-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-class-plugin.ts @@ -3,35 +3,46 @@ import { MarkdownBuilder } from "@simplrjs/markdown"; import * as path from "path"; import { GeneratorHelpers } from "../generator-helpers"; -import { - Plugin, - SupportedApiItemKindType, - PluginOptions, - PluginResult, - PluginResultData -} from "../contracts/plugin"; +import { SupportedApiItemKindType, PluginOptions, PluginResult } from "../contracts/plugin"; +import { ContainerPlugin, ContainerMembersKindsGroup } from "../abstractions/container-plugin"; -interface RenderMembers { - Heading: string; - Kinds: Contracts.ApiItemKinds[]; -} - -export class ApiClassPlugin implements Plugin { +export class ApiClassPlugin extends ContainerPlugin { public SupportedApiItemKinds(): SupportedApiItemKindType[] { return [GeneratorHelpers.ApiItemKinds.Class]; } - public CheckApiItem(item: Contracts.ApiItemDto): boolean { - return true; - } + public Render(data: PluginOptions): PluginResult { + const heading = path.basename(data.ApiItem.Name, path.extname(data.ApiItem.Name)); + const pluginResult: PluginResult = { + ...GeneratorHelpers.GetDefaultPluginResultData(), + ApiItem: data.ApiItem, + Reference: data.Reference, + Headings: [ + { + Heading: heading, + ApiItemId: data.Reference.Id + } + ] + }; - private renderMembers(data: PluginOptions): PluginResultData { - const references = GeneratorHelpers.GetApiItemReferences(data.ExtractedData, data.ApiItem.Members); - const renderedItems = references.map(x => data.GetItemPluginResult(x)); - const pluginResultData = GeneratorHelpers.GetDefaultPluginResultData(); - const builder = new MarkdownBuilder(); + // Resolve ApiItems from references. + const typeParameters = GeneratorHelpers + .GetApiItemsFromReference(data.ApiItem.TypeParameters, data.ExtractedData); - const list: RenderMembers[] = [ + // Header + pluginResult.Result = new MarkdownBuilder() + .Header(heading, 1) + .EmptyLine() + .Text(GeneratorHelpers.RenderApiItemMetadata(data.ApiItem)) + .Code(GeneratorHelpers.ClassToString( + data.ApiItem, + typeParameters, + data.Reference.Alias + ), GeneratorHelpers.DEFAULT_CODE_OPTIONS) + .GetOutput(); + + // ApiMembers + const memberKindsList: ContainerMembersKindsGroup[] = [ { Heading: "Index", Kinds: [Contracts.ApiItemKinds.Index] @@ -53,60 +64,7 @@ export class ApiClassPlugin implements Plugin { ] } ]; - - for (const memberKind of list) { - const pluginResultsByKind = renderedItems.filter(x => memberKind.Kinds.indexOf(x.ApiItem.ApiKind) !== -1); - - if (pluginResultsByKind.length > 0) { - builder - .Header(memberKind.Heading, 2) - .EmptyLine(); - - for (const member of pluginResultsByKind) { - GeneratorHelpers.MergePluginResultData(pluginResultData, member); - - builder - .Text(member.Result) - .EmptyLine(); - } - } - } - - pluginResultData.Result = builder.GetOutput(); - return pluginResultData; - } - - public Render(data: PluginOptions): PluginResult { - const typeParameters = GeneratorHelpers - .GetApiItemsFromReference(data.ApiItem.TypeParameters, data.ExtractedData); - - const pluginResult: PluginResult = { - ApiItem: data.ApiItem, - Reference: data.Reference, - ...GeneratorHelpers.GetDefaultPluginResultData() - }; - const heading = path.basename(data.ApiItem.Name, path.extname(data.ApiItem.Name)); - pluginResult.Headings = [ - { - Heading: heading, - ApiItemId: data.Reference.Id - } - ]; - - // Header - const builder = new MarkdownBuilder() - .Header(heading, 1) - .EmptyLine() - .Text(GeneratorHelpers.RenderApiItemMetadata(data.ApiItem)) - .Code(GeneratorHelpers.ClassToString( - data.ApiItem, - typeParameters, - data.Reference.Alias - ), GeneratorHelpers.DEFAULT_CODE_OPTIONS); - pluginResult.Result = builder.GetOutput(); - - // ApiMembers - const members = this.renderMembers(data); + const members = this.RenderMembersGroups(memberKindsList, data); GeneratorHelpers.MergePluginResultData(pluginResult, members); return pluginResult; diff --git a/packages/ts-docs-gen/src/plugins/api-class-property-plugin.ts b/packages/ts-docs-gen/src/plugins/api-class-property-plugin.ts index 1df3b160..36144af9 100644 --- a/packages/ts-docs-gen/src/plugins/api-class-property-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-class-property-plugin.ts @@ -1,28 +1,31 @@ import { Contracts } from "ts-extractor"; import { MarkdownBuilder } from "@simplrjs/markdown"; -import { Plugin, SupportedApiItemKindType, PluginOptions, PluginResult } from "../contracts/plugin"; + +import { SupportedApiItemKindType, PluginOptions, PluginResult } from "../contracts/plugin"; import { GeneratorHelpers } from "../generator-helpers"; +import { BasePlugin } from "../abstractions/base-plugin"; -export class ApiClassPropertyPlugin implements Plugin { +export class ApiClassPropertyPlugin extends BasePlugin { public SupportedApiItemKinds(): SupportedApiItemKindType[] { return [GeneratorHelpers.ApiItemKinds.ClassProperty]; } - public CheckApiItem(item: Contracts.ApiItemDto): boolean { - return true; - } - public Render(options: PluginOptions): PluginResult { - const pluginResultData = GeneratorHelpers.GetDefaultPluginResultData(); - const builder = new MarkdownBuilder(); - const heading = options.Reference.Alias; - pluginResultData.Headings.push({ ApiItemId: options.Reference.Id, Heading: heading }); - - const typeStringDto = GeneratorHelpers.TypeDtoToMarkdownString(options.ApiItem.Type); - pluginResultData.UsedReferences = pluginResultData.UsedReferences.concat(typeStringDto.References); + const pluginResult: PluginResult = { + ...GeneratorHelpers.GetDefaultPluginResultData(), + ApiItem: options.ApiItem, + Reference: options.Reference, + Headings: [ + { + ApiItemId: options.Reference.Id, + Heading: heading + } + ] + }; - builder + // Header + pluginResult.Result = new MarkdownBuilder() .Header(heading, 3) .EmptyLine() .Text(GeneratorHelpers.RenderApiItemMetadata(options.ApiItem)) @@ -30,17 +33,11 @@ export class ApiClassPropertyPlugin implements Plugin { +export class ApiDefaultPlugin extends BasePlugin { public SupportedApiItemKinds(): SupportedApiItemKindType[] { return [GeneratorHelpers.ApiItemKinds.Any]; } - public CheckApiItem(item: Contracts.ApiItemDto): boolean { - return true; - } - - public Render(data: PluginOptions): PluginResult { - const heading = `${data.ApiItem.ApiKind}: ${data.Reference.Alias}`; - const headings: PluginHeading[] = [ - { - ApiItemId: data.Reference.Id, - Heading: heading - } - ]; + public Render(options: PluginOptions): PluginResult { + const heading = `${options.ApiItem.ApiKind}: ${options.Reference.Alias}`; + const pluginResult: PluginResult = { + ...GeneratorHelpers.GetDefaultPluginResultData(), + ApiItem: options.ApiItem, + Reference: options.Reference, + Headings: [ + { + Heading: heading, + ApiItemId: options.Reference.Id + } + ] + }; - const result: string[] = [ - MarkdownGenerator.Header(heading, 2) - ]; + pluginResult.Result = new MarkdownBuilder() + .Header(heading, 3) + .EmptyLine() + .Bold(`Warning: unsupported api item kind ${options.ApiItem.ApiKind}!`) + .EmptyLine() + .Text(GeneratorHelpers.RenderApiItemMetadata(options.ApiItem)) + .GetOutput(); - return { - ApiItem: data.ApiItem, - Reference: data.Reference, - Headings: headings, - UsedReferences: [], - Result: result, - }; + return pluginResult; } } diff --git a/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts b/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts index 783d1a87..63148d96 100644 --- a/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts @@ -2,11 +2,10 @@ import { Contracts } from "ts-extractor"; import { MarkdownGenerator, MarkdownBuilder } from "@simplrjs/markdown"; import { GeneratorHelpers } from "../generator-helpers"; -import { Plugin, SupportedApiItemKindType, PluginResult, PluginOptions, PluginHeading } from "../contracts/plugin"; +import { SupportedApiItemKindType, PluginResult, PluginOptions } from "../contracts/plugin"; +import { BasePlugin } from "../abstractions/base-plugin"; -// TODO: const enums implementation. - -export class ApiEnumPlugin implements Plugin { +export class ApiEnumPlugin extends BasePlugin { public SupportedApiItemKinds(): SupportedApiItemKindType[] { return [GeneratorHelpers.ApiItemKinds.Enum]; } @@ -15,7 +14,7 @@ export class ApiEnumPlugin implements Plugin { return true; } - private constructEnumTable(members: Contracts.ApiEnumMemberDto[]): string[] { + private renderEnumTable(members: Contracts.ApiEnumMemberDto[]): string[] { // Table header. const header = ["Name", "Value", "Description"]; const content = members.map(x => [x.Name, x.Value, x.Metadata.DocumentationComment]); @@ -23,34 +22,42 @@ export class ApiEnumPlugin implements Plugin { return MarkdownGenerator.Table(header, content, { removeColumnIfEmpty: true }); } - public Render(data: PluginOptions): PluginResult { - const heading: string = data.Reference.Alias; - const headings: PluginHeading[] = [ - { - ApiItemId: data.Reference.Id, - Heading: heading - } - ]; + public Render(options: PluginOptions): PluginResult { + const heading: string = options.Reference.Alias; + const pluginResult: PluginResult = { + ...GeneratorHelpers.GetDefaultPluginResultData(), + ApiItem: options.ApiItem, + Reference: options.Reference, + Headings: [ + { + Heading: heading, + ApiItemId: options.Reference.Id + } + ] + }; + // Enum members const enumMembers = GeneratorHelpers.GetApiItemsFromReference( - data.ApiItem.Members, - data.ExtractedData + options.ApiItem.Members, + options.ExtractedData ); - const builder = new MarkdownBuilder() - .Header(heading, 2) + + pluginResult.Result = new MarkdownBuilder() + .Header(heading, 3) .EmptyLine() - .Text(GeneratorHelpers.RenderApiItemMetadata(data.ApiItem)) + .Text(GeneratorHelpers.RenderApiItemMetadata(options.ApiItem)) .EmptyLine() - .Code(GeneratorHelpers.EnumToString(data.Reference.Alias, enumMembers), GeneratorHelpers.DEFAULT_CODE_OPTIONS) + .Code(GeneratorHelpers.ApiEnumToString( + options.ApiItem, + enumMembers, + options.Reference.Alias + ), GeneratorHelpers.DEFAULT_CODE_OPTIONS) .EmptyLine() - .Text(this.constructEnumTable(enumMembers)); - - return { - ApiItem: data.ApiItem, - Reference: data.Reference, - Headings: headings, - UsedReferences: [], - Result: builder.GetOutput() - }; + .Bold("Members") + .EmptyLine() + .Text(this.renderEnumTable(enumMembers)) + .GetOutput(); + + return pluginResult; } } diff --git a/packages/ts-docs-gen/src/plugins/api-function-plugin.ts b/packages/ts-docs-gen/src/plugins/api-function-plugin.ts index 99d4ea58..bee15bf0 100644 --- a/packages/ts-docs-gen/src/plugins/api-function-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-function-plugin.ts @@ -2,131 +2,60 @@ import { Contracts } from "ts-extractor"; import { MarkdownBuilder } from "@simplrjs/markdown"; import { GeneratorHelpers } from "../generator-helpers"; -import { SupportedApiItemKindType, Plugin, PluginResult, PluginOptions, PluginHeading } from "../contracts/plugin"; -import { ApiFunctionDto } from "ts-extractor/dist/contracts"; +import { SupportedApiItemKindType, PluginResult, PluginOptions } from "../contracts/plugin"; +import { FunctionLikePlugin } from "../abstractions/function-like-plugin"; -export class ApiFunctionPlugin implements Plugin { +export class ApiFunctionPlugin extends FunctionLikePlugin { public SupportedApiItemKinds(): SupportedApiItemKindType[] { return [GeneratorHelpers.ApiItemKinds.Function]; } - public CheckApiItem(item: ApiFunctionDto): boolean { - return true; - } - - // TODO: add description from @param jsdoc tag. - private resolveFunctionParameters(parameters: Contracts.ApiParameterDto[]): GeneratorHelpers.ReferenceDto { - if (parameters.length === 0) { - return { - References: [], - Text: [] - }; - } - - const table = GeneratorHelpers.ApiParametersToTableString(parameters); - const builder = new MarkdownBuilder() - .Header("Parameters", 3) - .EmptyLine() - .Text(table.Text) - .EmptyLine(); - - return { - Text: builder.GetOutput(), - References: table.References + public Render(options: PluginOptions): PluginResult { + // Parameters + const apiParameters = GeneratorHelpers + .GetApiItemsFromReference(options.ApiItem.Parameters, options.ExtractedData); + // TypeParameters + const apiTypeParameters = GeneratorHelpers + .GetApiItemsFromReference(options.ApiItem.TypeParameters, options.ExtractedData); + + const heading = GeneratorHelpers.MethodToSimpleString(options.Reference.Alias, apiParameters); + const pluginResult: PluginResult = { + ...GeneratorHelpers.GetDefaultPluginResultData(), + ApiItem: options.ApiItem, + Reference: options.Reference, + Headings: [ + { + Heading: heading, + ApiItemId: options.Reference.Id + } + ] }; - } - - private resolveFunctionTypeParameters(typeParameters: Contracts.ApiTypeParameterDto[]): GeneratorHelpers.ReferenceDto { - if (typeParameters.length === 0) { - return { References: [], Text: [] }; - } - - const typeParametersTable = GeneratorHelpers.ApiTypeParametersTableToString(typeParameters); - const text = new MarkdownBuilder() - .Header("Type parameters", 3) - .EmptyLine() - .Text(typeParametersTable.Text) - .EmptyLine() - .GetOutput(); - - return { - References: typeParametersTable.References, - Text: text - }; - } - - private resolveReturnType(typeDto?: Contracts.TypeDto): GeneratorHelpers.ReferenceDto { - if (typeDto == null) { - return { - References: [], - Text: [] - }; - } - const parsedReturnType = GeneratorHelpers.TypeDtoToMarkdownString(typeDto); - - const text = new MarkdownBuilder() - .Header("Return type", 3) - .EmptyLine() - .Text(parsedReturnType.Text) + // Header + pluginResult.Result = new MarkdownBuilder() + .Header(heading, 3) .EmptyLine() + .Text(GeneratorHelpers.RenderApiItemMetadata(options.ApiItem)) + .Code(GeneratorHelpers.ApiFunctionToString( + options.ApiItem, + apiTypeParameters, + apiParameters, + options.Reference.Alias + ), GeneratorHelpers.DEFAULT_CODE_OPTIONS) .GetOutput(); - return { - Text: text, - References: parsedReturnType.References - }; - } - - public Render(data: PluginOptions): PluginResult { - const alias = data.Reference.Alias; - - const headings: PluginHeading[] = [ - { - ApiItemId: data.Reference.Id, - Heading: alias - } - ]; + // TypeParameters + const typeParametersResult = this.RenderTypeParameters(apiTypeParameters); + GeneratorHelpers.MergePluginResultData(pluginResult, typeParametersResult); - const parameters = GeneratorHelpers.GetApiItemsFromReference( - data.ApiItem.Parameters, - data.ExtractedData - ); - const resolvedParametersDto = this.resolveFunctionParameters(parameters); + // Parameters + const parametersResult = this.RenderParameters(apiParameters); + GeneratorHelpers.MergePluginResultData(pluginResult, parametersResult); - const typeParameters = GeneratorHelpers.GetApiItemsFromReference( - data.ApiItem.TypeParameters, - data.ExtractedData - ); - const resolvedTypeParametersDto = this.resolveFunctionTypeParameters(typeParameters); + // ReturnType + const returnTypeResult = this.RenderReturnType(options.ApiItem.ReturnType); + GeneratorHelpers.MergePluginResultData(pluginResult, returnTypeResult); - const resolvedReturnTypeDto = this.resolveReturnType(data.ApiItem.ReturnType); - - const builder = new MarkdownBuilder() - .Header(GeneratorHelpers.MethodToSimpleString(alias || data.ApiItem.Name, parameters), 2) - .EmptyLine() - .Text(GeneratorHelpers.RenderApiItemMetadata(data.ApiItem)) - .Code(GeneratorHelpers.ApiFunctionToString( - data.ApiItem, - typeParameters, - parameters, - data.Reference.Alias - ), GeneratorHelpers.DEFAULT_CODE_OPTIONS) - .EmptyLine() - .Text(resolvedTypeParametersDto.Text) - .Text(resolvedParametersDto.Text) - .Text(resolvedReturnTypeDto.Text); - - return { - ApiItem: data.ApiItem, - Reference: data.Reference, - Headings: headings, - UsedReferences: [ - ...resolvedParametersDto.References, - ...resolvedTypeParametersDto.References, - ...resolvedReturnTypeDto.References - ], - Result: builder.GetOutput() - }; + return pluginResult; } } diff --git a/packages/ts-docs-gen/src/plugins/api-index-plugin.ts b/packages/ts-docs-gen/src/plugins/api-index-plugin.ts index 9f052af1..d8b2b228 100644 --- a/packages/ts-docs-gen/src/plugins/api-index-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-index-plugin.ts @@ -1,50 +1,47 @@ import { Contracts } from "ts-extractor"; -import { MarkdownBuilder } from "@simplrjs/markdown"; +import { MarkdownBuilder, MarkdownGenerator as md } from "@simplrjs/markdown"; -import { Plugin, SupportedApiItemKindType, PluginResult, PluginOptions } from "../contracts/plugin"; +import { SupportedApiItemKindType, PluginResult, PluginOptions } from "../contracts/plugin"; import { GeneratorHelpers } from "../generator-helpers"; +import { BasePlugin } from "../abstractions/base-plugin"; -export class ApiIndexPlugin implements Plugin { +export class ApiIndexPlugin extends BasePlugin { public SupportedApiItemKinds(): SupportedApiItemKindType[] { return [GeneratorHelpers.ApiItemKinds.Index]; } - public CheckApiItem(item: Contracts.ApiIndexDto): boolean { - return true; - } - - public Render(data: PluginOptions): PluginResult { - const parameter = data.ExtractedData.Registry[data.ApiItem.Parameter] as Contracts.ApiParameterDto; + public Render(options: PluginOptions): PluginResult { + const pluginResult: PluginResult = { + ...GeneratorHelpers.GetDefaultPluginResultData(), + ApiItem: options.ApiItem, + Reference: options.Reference + }; + // Parameter + const parameter = options.ExtractedData.Registry[options.ApiItem.Parameter] as Contracts.ApiParameterDto; + // Types const parameterType = GeneratorHelpers.TypeDtoToMarkdownString(parameter.Type); - const indexType = GeneratorHelpers.TypeDtoToMarkdownString(data.ApiItem.Type); - - const indexDeclarationString = GeneratorHelpers.ApiIndexToString(parameter, data.ApiItem.Type, data.ApiItem.IsReadonly); + const indexType = GeneratorHelpers.TypeDtoToMarkdownString(options.ApiItem.Type); + GeneratorHelpers.MergePluginResultData(pluginResult, { + UsedReferences: [ + ...parameterType.References, + ...indexType.References + ] + }); + // Header + const indexDeclarationString = GeneratorHelpers.ApiIndexToString(parameter, options.ApiItem.Type, options.ApiItem.IsReadonly); const builder = new MarkdownBuilder() .Code(indexDeclarationString, GeneratorHelpers.DEFAULT_CODE_OPTIONS) .EmptyLine(); - if (data.ApiItem.IsReadonly) { - builder - .Text("Readonly.") - .EmptyLine(); - } - - builder - .Text(`Index \`${parameter.Name}\` - ${parameterType.Text}`) - .EmptyLine() - .Text(`Type - ${indexType.Text}`); + pluginResult.Result = builder + .UnorderedList([ + `${md.Italic("Parameter")} ${md.InlineCode(parameter.Name)} - ${parameterType.Text}`, + `${md.Italic("Type")} ${indexType.Text}` + ]) + .GetOutput(); - return { - ApiItem: data.ApiItem, - Reference: data.Reference, - Headings: [], - Result: builder.GetOutput(), - UsedReferences: [ - ...parameterType.References, - ...indexType.References - ] - }; + return pluginResult; } } 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 6bc8c1b1..2d008c14 100644 --- a/packages/ts-docs-gen/src/plugins/api-interface-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-interface-plugin.ts @@ -1,7 +1,7 @@ import { Contracts } from "ts-extractor"; import { MarkdownBuilder, MarkdownGenerator } from "@simplrjs/markdown"; + import { - Plugin, SupportedApiItemKindType, PluginResult, PluginOptions, @@ -10,54 +10,26 @@ import { } from "../contracts/plugin"; import { GeneratorHelpers } from "../generator-helpers"; import { ApiItemReference } from "../contracts/api-item-reference"; +import { BasePlugin } from "../abstractions/base-plugin"; interface ExtractedItemDto { Reference: ApiItemReference; ApiItem: TApiItemDto; } -export class ApiInterfacePlugin implements Plugin { +export class ApiInterfacePlugin extends BasePlugin { public SupportedApiItemKinds(): SupportedApiItemKindType[] { return [GeneratorHelpers.ApiItemKinds.Interface]; } - public CheckApiItem(item: Contracts.ApiInterfaceDto): boolean { - return true; - } - - private renderTypeParameters(pluginOptions: PluginOptions): PluginResultData { - const typeParameters = GeneratorHelpers.GetApiItemsFromReference( - pluginOptions.ApiItem.TypeParameters, - pluginOptions.ExtractedData - ); - - if (typeParameters.length === 0) { - return GeneratorHelpers.GetDefaultPluginResultData(); - } - - const typeParametersTable = GeneratorHelpers.ApiTypeParametersTableToString(typeParameters); - const text = new MarkdownBuilder() - .EmptyLine() - .Header("Type parameters", 3) - .EmptyLine() - .Text(typeParametersTable.Text) - .GetOutput(); - - return { - Result: text, - UsedReferences: typeParametersTable.References, - Headings: [] - }; - } - - private renderConstraintTypes(apiItem: Contracts.ApiInterfaceDto): PluginResultData { + private renderConstraintTypes(apiItem: Contracts.ApiInterfaceDto): PluginResultData | undefined { if (apiItem.Extends.length === 0) { - return GeneratorHelpers.GetDefaultPluginResultData(); + return undefined; } const builder = new MarkdownBuilder() .EmptyLine() - .Header("Extends", 3); + .Bold("Extends"); const references = []; @@ -70,32 +42,32 @@ export class ApiInterfacePlugin implements Plugin { } return { + ...GeneratorHelpers.GetDefaultPluginResultData(), UsedReferences: references, Result: builder.GetOutput(), - Headings: [] }; } - private renderPropertyMembers(memberItems: ExtractedItemDto[]): PluginResultData { + private renderPropertyMembers(memberItems: ExtractedItemDto[]): PluginResultData | undefined { const apiItems = memberItems.filter>( this.isReferenceOfApiItemKind.bind(undefined, Contracts.ApiItemKinds.Property) ).map(x => x.ApiItem); if (apiItems.length === 0) { - return GeneratorHelpers.GetDefaultPluginResultData(); + return undefined; } const table = GeneratorHelpers.ApiPropertiesToTableString(apiItems); const builder = new MarkdownBuilder() .EmptyLine() - .Header("Properties", 3) + .Bold("Properties") .EmptyLine() .Text(table.Text); return { + ...GeneratorHelpers.GetDefaultPluginResultData(), UsedReferences: table.References, Result: builder.GetOutput(), - Headings: [] }; } @@ -111,15 +83,15 @@ export class ApiInterfacePlugin implements Plugin { apiItemKind: Contracts.ApiItemKinds, memberItems: ExtractedItemDto[], getPluginResult: GetItemPluginResultHandler - ): PluginResultData { + ): PluginResultData | undefined { const items = memberItems.filter(this.isReferenceOfApiItemKind.bind(undefined, apiItemKind)); if (items.length === 0) { - return GeneratorHelpers.GetDefaultPluginResultData(); + return undefined; } const pluginResult = GeneratorHelpers.GetDefaultPluginResultData(); - pluginResult.Result.push("", MarkdownGenerator.Header(title, 3)); + pluginResult.Result.push("", MarkdownGenerator.Header(title, 4)); for (const item of items) { pluginResult.Result.push(""); @@ -131,42 +103,43 @@ export class ApiInterfacePlugin implements Plugin { return pluginResult; } - public Render(data: PluginOptions): PluginResult { - const alias = data.Reference.Alias; - const header = GeneratorHelpers.ApiInterfaceToSimpleString(alias, data.ApiItem); + public Render(options: PluginOptions): PluginResult { + const heading = options.Reference.Alias; const pluginResult: PluginResult = { ...GeneratorHelpers.GetDefaultPluginResultData(), - ApiItem: data.ApiItem, - Reference: data.Reference, + ApiItem: options.ApiItem, + Reference: options.Reference, Headings: [ { - ApiItemId: data.Reference.Id, - Heading: header + ApiItemId: options.Reference.Id, + Heading: heading } ] }; - const memberReferences = GeneratorHelpers.GetApiItemReferences(data.ExtractedData, data.ApiItem.Members); + const memberReferences = GeneratorHelpers.GetApiItemReferences(options.ExtractedData, options.ApiItem.Members); const memberItems = memberReferences.map(itemReference => ({ Reference: itemReference, - ApiItem: data.ExtractedData.Registry[itemReference.Id] + ApiItem: options.ExtractedData.Registry[itemReference.Id] })); - const interfaceString = GeneratorHelpers.ApiInterfaceToString(data.ApiItem, data.ExtractedData); + const interfaceString = GeneratorHelpers.ApiInterfaceToString(options.ApiItem, options.ExtractedData); const builder = new MarkdownBuilder() - .Header(header, 2) + .Header(heading, 3) .EmptyLine() - .Text(GeneratorHelpers.RenderApiItemMetadata(data.ApiItem)) + .Text(GeneratorHelpers.RenderApiItemMetadata(options.ApiItem)) .Code(interfaceString, GeneratorHelpers.DEFAULT_CODE_OPTIONS); pluginResult.Result = builder.GetOutput(); // Type parameters - const typeParametersResult = this.renderTypeParameters(data); + const apiTypeParameters = GeneratorHelpers + .GetApiItemsFromReference(options.ApiItem.TypeParameters, options.ExtractedData); + const typeParametersResult = this.RenderTypeParameters(apiTypeParameters); GeneratorHelpers.MergePluginResultData(pluginResult, typeParametersResult); // Constraint types - const constraintTypesResult = this.renderConstraintTypes(data.ApiItem); + const constraintTypesResult = this.renderConstraintTypes(options.ApiItem); GeneratorHelpers.MergePluginResultData(pluginResult, constraintTypesResult); // Construct items @@ -174,7 +147,7 @@ export class ApiInterfacePlugin implements Plugin { "Construct", Contracts.ApiItemKinds.Construct, memberItems, - data.GetItemPluginResult + options.GetItemPluginResult ); GeneratorHelpers.MergePluginResultData(pluginResult, constructMembersResult); @@ -183,7 +156,7 @@ export class ApiInterfacePlugin implements Plugin { "Call", Contracts.ApiItemKinds.Call, memberItems, - data.GetItemPluginResult + options.GetItemPluginResult ); GeneratorHelpers.MergePluginResultData(pluginResult, callMembersResult); @@ -192,7 +165,7 @@ export class ApiInterfacePlugin implements Plugin { "Index signatures", Contracts.ApiItemKinds.Index, memberItems, - data.GetItemPluginResult + options.GetItemPluginResult ); GeneratorHelpers.MergePluginResultData(pluginResult, indexMembersResult); @@ -201,7 +174,7 @@ export class ApiInterfacePlugin implements Plugin { "Methods", Contracts.ApiItemKinds.Method, memberItems, - data.GetItemPluginResult + options.GetItemPluginResult ); GeneratorHelpers.MergePluginResultData(pluginResult, methodMembersResult); diff --git a/packages/ts-docs-gen/src/plugins/api-namespace-plugin.ts b/packages/ts-docs-gen/src/plugins/api-namespace-plugin.ts index 056316c2..a20f0c92 100644 --- a/packages/ts-docs-gen/src/plugins/api-namespace-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-namespace-plugin.ts @@ -1,92 +1,71 @@ import { Contracts } from "ts-extractor"; import { MarkdownBuilder } from "@simplrjs/markdown"; +import * as path from "path"; import { GeneratorHelpers } from "../generator-helpers"; -import { PluginMember, Plugin, SupportedApiItemKindType, PluginOptions, PluginResult, PluginHeading } from "../contracts/plugin"; +import { SupportedApiItemKindType, PluginOptions, PluginResult } from "../contracts/plugin"; +import { ContainerPlugin, ContainerMembersKindsGroup } from "../abstractions/container-plugin"; -interface RenderItems { - References: string[]; - Output: string[]; - Members: PluginMember[]; -} - -export class ApiNamespacePlugin implements Plugin { +export class ApiNamespacePlugin extends ContainerPlugin { public SupportedApiItemKinds(): SupportedApiItemKindType[] { return [GeneratorHelpers.ApiItemKinds.Namespace]; } - public CheckApiItem(item: Contracts.ApiItemDto): boolean { - return true; - } - - private renderItems(data: PluginOptions): RenderItems { - const references = GeneratorHelpers.GetApiItemReferences(data.ExtractedData, data.ApiItem.Members); - const referencesList: string[] = []; - const members: PluginMember[] = []; - const builder = new MarkdownBuilder(); - - for (const reference of references) { - const apiItem = data.ExtractedData.Registry[reference.Id]; - - switch (apiItem.ApiKind) { - case Contracts.ApiItemKinds.Namespace: - case Contracts.ApiItemKinds.Class: { - - const renderedItem = data.GetItemPluginResult(reference); - members.push({ - Reference: reference, - PluginResult: renderedItem - }); - - builder - .Text(md => md.Header(md.Link(renderedItem.ApiItem.Name, reference.Id, true), 2)) - .EmptyLine(); - referencesList.push(reference.Id); - break; - } - default: { - const renderedItem = data.GetItemPluginResult(reference); - // Something to do with heading. Maybe heading reference registry? - builder - .Text(renderedItem.Result) - .EmptyLine(); + public Render(data: PluginOptions): PluginResult { + const heading = path.basename(data.ApiItem.Name, path.extname(data.ApiItem.Name)); + const pluginResult: PluginResult = { + ...GeneratorHelpers.GetDefaultPluginResultData(), + ApiItem: data.ApiItem, + Reference: data.Reference, + Headings: [ + { + Heading: heading, + ApiItemId: data.Reference.Id } - } - } - - return { - References: referencesList, - Output: builder.GetOutput(), - Members: members + ] }; - } - - public Render(data: PluginOptions): PluginResult { - const heading = data.Reference.Alias; - const headings: PluginHeading[] = [ - { - Heading: heading, - ApiItemId: data.Reference.Id - } - ]; - - const renderedItems = this.renderItems(data); - const references: string[] = renderedItems.References; // Header - const builder = new MarkdownBuilder() + pluginResult.Result = new MarkdownBuilder() .Header(heading, 1) .EmptyLine() .Text(GeneratorHelpers.RenderApiItemMetadata(data.ApiItem)) - .Text(renderedItems.Output); + .GetOutput(); - return { - ApiItem: data.ApiItem, - Reference: data.Reference, - Headings: headings, - UsedReferences: references, - Result: builder.GetOutput(), - Members: renderedItems.Members - }; + // Members + const memberKindsList: ContainerMembersKindsGroup[] = [ + { + Heading: "Functions", + Kinds: [Contracts.ApiItemKinds.Function] + }, + { + Heading: "Interfaces", + Kinds: [Contracts.ApiItemKinds.Interface] + }, + { + Heading: "Types", + Kinds: [Contracts.ApiItemKinds.Type] + }, + { + Heading: "Enums", + Kinds: [Contracts.ApiItemKinds.Enum] + }, + { + Heading: "Classes", + Kinds: [Contracts.ApiItemKinds.Class] + }, + { + Heading: "Namespaces", + Kinds: [Contracts.ApiItemKinds.Namespace] + }, + { + Heading: "Variables", + Kinds: [Contracts.ApiItemKinds.Variable] + } + ]; + const renderedMembers = this.RenderMembersGroups(memberKindsList, data); + GeneratorHelpers.MergePluginResultData(pluginResult, renderedMembers); + + return pluginResult; } } diff --git a/packages/ts-docs-gen/src/plugins/api-source-file-plugin.ts b/packages/ts-docs-gen/src/plugins/api-source-file-plugin.ts index 03d86f4b..fbc6c42f 100644 --- a/packages/ts-docs-gen/src/plugins/api-source-file-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-source-file-plugin.ts @@ -3,105 +3,69 @@ import { MarkdownBuilder } from "@simplrjs/markdown"; import * as path from "path"; import { GeneratorHelpers } from "../generator-helpers"; -import { PluginMember, Plugin, SupportedApiItemKindType, PluginOptions, PluginResult, PluginHeading } from "../contracts/plugin"; +import { SupportedApiItemKindType, PluginOptions, PluginResult } from "../contracts/plugin"; +import { ContainerPlugin, ContainerMembersKindsGroup } from "../abstractions/container-plugin"; -interface RenderItems { - References: string[]; - Headings: PluginHeading[]; - Output: string[]; - Members: PluginMember[]; -} - -export class ApiSourceFilePlugin implements Plugin { +export class ApiSourceFilePlugin extends ContainerPlugin { public SupportedApiItemKinds(): SupportedApiItemKindType[] { return [GeneratorHelpers.ApiItemKinds.SourceFile]; } - public CheckApiItem(item: Contracts.ApiItemDto): boolean { - return true; - } - - // TODO: Move this to helpers. - private renderItems(data: PluginOptions): RenderItems { - const references = GeneratorHelpers.GetApiItemReferences(data.ExtractedData, data.ApiItem.Members); - let referencesList: string[] = []; - let headingsList: PluginHeading[] = []; - const members: PluginMember[] = []; - const builder = new MarkdownBuilder(); - - for (const reference of references) { - const apiItem = data.ExtractedData.Registry[reference.Id]; - - if (data.IsPluginResultExists(reference)) { - builder - .Text(md => md.Header(md.Link(apiItem.Name, reference.Id, true), 2)) - .EmptyLine(); - referencesList.push(reference.Id); - } else { - switch (apiItem.ApiKind) { - case Contracts.ApiItemKinds.Namespace: - case Contracts.ApiItemKinds.Class: { - - const renderedItem = data.GetItemPluginResult(reference); - members.push({ - Reference: reference, - PluginResult: renderedItem - }); - - builder - .Text(md => md.Header(md.Link(renderedItem.ApiItem.Name, reference.Id, true), 2)) - .EmptyLine(); - referencesList.push(reference.Id); - break; - } - default: { - const renderedItem = data.GetItemPluginResult(reference); - builder - .Text(renderedItem.Result) - .EmptyLine(); - - headingsList = headingsList.concat(renderedItem.Headings); - referencesList = referencesList.concat(renderedItem.UsedReferences); - } - } - } - } - - return { - References: referencesList, - Headings: headingsList, - Output: builder.GetOutput(), - Members: members - }; - } - public Render(data: PluginOptions): PluginResult { const heading = path.basename(data.ApiItem.Name, path.extname(data.ApiItem.Name)); - let headings: PluginHeading[] = [ - { - Heading: heading, - ApiItemId: data.Reference.Id - } - ]; - - const renderedItems = this.renderItems(data); - const references: string[] = renderedItems.References; - headings = headings.concat(renderedItems.Headings); + const pluginResult: PluginResult = { + ...GeneratorHelpers.GetDefaultPluginResultData(), + ApiItem: data.ApiItem, + Reference: data.Reference, + Headings: [ + { + Heading: heading, + ApiItemId: data.Reference.Id + } + ] + }; // Header - const builder = new MarkdownBuilder() + pluginResult.Result = new MarkdownBuilder() .Header(heading, 1) .EmptyLine() .Text(GeneratorHelpers.RenderApiItemMetadata(data.ApiItem)) - .Text(renderedItems.Output); + .GetOutput(); - return { - ApiItem: data.ApiItem, - Reference: data.Reference, - Headings: headings, - UsedReferences: references, - Result: builder.GetOutput(), - Members: renderedItems.Members - }; + // Members + const memberKindsList: ContainerMembersKindsGroup[] = [ + { + Heading: "Functions", + Kinds: [Contracts.ApiItemKinds.Function] + }, + { + Heading: "Interfaces", + Kinds: [Contracts.ApiItemKinds.Interface] + }, + { + Heading: "Types", + Kinds: [Contracts.ApiItemKinds.Type] + }, + { + Heading: "Enums", + Kinds: [Contracts.ApiItemKinds.Enum] + }, + { + Heading: "Classes", + Kinds: [Contracts.ApiItemKinds.Class] + }, + { + Heading: "Namespaces", + Kinds: [Contracts.ApiItemKinds.Namespace] + }, + { + Heading: "Variables", + Kinds: [Contracts.ApiItemKinds.Variable] + } + ]; + const members = this.RenderMembersGroups(memberKindsList, data); + GeneratorHelpers.MergePluginResultData(pluginResult, members); + + return pluginResult; } } diff --git a/packages/ts-docs-gen/src/plugins/api-type-plugin.ts b/packages/ts-docs-gen/src/plugins/api-type-plugin.ts index bd652f03..4e83a89e 100644 --- a/packages/ts-docs-gen/src/plugins/api-type-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-type-plugin.ts @@ -2,44 +2,46 @@ import { Contracts } from "ts-extractor"; import { MarkdownBuilder } from "@simplrjs/markdown"; import { GeneratorHelpers } from "../generator-helpers"; -import { Plugin, SupportedApiItemKindType, PluginOptions, PluginResult, PluginHeading } from "../contracts/plugin"; +import { SupportedApiItemKindType, PluginOptions, PluginResult } from "../contracts/plugin"; +import { BasePlugin } from "../abstractions/base-plugin"; -export class ApiTypePlugin implements Plugin { +export class ApiTypePlugin extends BasePlugin { public SupportedApiItemKinds(): SupportedApiItemKindType[] { return [GeneratorHelpers.ApiItemKinds.Type]; } - public CheckApiItem(item: Contracts.ApiItemDto): boolean { - return true; - } - - public Render(data: PluginOptions): PluginResult { - const heading = data.Reference.Alias; - const headings: PluginHeading[] = [ - { - Heading: heading, - ApiItemId: data.Reference.Id - } - ]; - const typeStringDto = GeneratorHelpers.TypeDtoToMarkdownString(data.ApiItem.Type); + public Render(options: PluginOptions): PluginResult { + const heading = options.Reference.Alias; + const pluginResult: PluginResult = { + ...GeneratorHelpers.GetDefaultPluginResultData(), + ApiItem: options.ApiItem, + Reference: options.Reference, + Headings: [ + { + Heading: heading, + ApiItemId: options.Reference.Id + } + ] + }; // Header - const builder = new MarkdownBuilder() - .Header(heading, 2) - .EmptyLine() - .Text(GeneratorHelpers.RenderApiItemMetadata(data.ApiItem)) - .Code(GeneratorHelpers.ApiTypeToString(data.ApiItem), GeneratorHelpers.DEFAULT_CODE_OPTIONS) + pluginResult.Result = new MarkdownBuilder() + .Header(heading, 3) .EmptyLine() - .Header("Type", 3) - .EmptyLine() - .Text(typeStringDto.Text); + .Text(GeneratorHelpers.RenderApiItemMetadata(options.ApiItem)) + .Code(GeneratorHelpers.ApiTypeToString(options.ApiItem), GeneratorHelpers.DEFAULT_CODE_OPTIONS) + .GetOutput(); - return { - ApiItem: data.ApiItem, - Reference: data.Reference, - Headings: headings, - UsedReferences: typeStringDto.References, - Result: builder.GetOutput() - }; + // TypeParameters + const apiTypeParameters = GeneratorHelpers + .GetApiItemsFromReference(options.ApiItem.TypeParameters, options.ExtractedData); + const typeParametersResult = this.RenderTypeParameters(apiTypeParameters); + GeneratorHelpers.MergePluginResultData(pluginResult, typeParametersResult); + + // Type + const typeResult = this.RenderType(options.ApiItem.Type); + GeneratorHelpers.MergePluginResultData(pluginResult, typeResult); + + return pluginResult; } } diff --git a/packages/ts-docs-gen/src/plugins/api-variable-plugin.ts b/packages/ts-docs-gen/src/plugins/api-variable-plugin.ts index d2757500..1f01c288 100644 --- a/packages/ts-docs-gen/src/plugins/api-variable-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-variable-plugin.ts @@ -2,43 +2,42 @@ import { Contracts } from "ts-extractor"; import { MarkdownBuilder } from "@simplrjs/markdown"; import { GeneratorHelpers } from "../generator-helpers"; -import { Plugin, SupportedApiItemKindType, PluginOptions, PluginResult, PluginHeading } from "../contracts/plugin"; +import { SupportedApiItemKindType, PluginOptions, PluginResult } from "../contracts/plugin"; +import { BasePlugin } from "../abstractions/base-plugin"; -export class ApiVariablePlugin implements Plugin { +export class ApiVariablePlugin extends BasePlugin { public SupportedApiItemKinds(): SupportedApiItemKindType[] { return [GeneratorHelpers.ApiItemKinds.Variable]; } - public CheckApiItem(item: Contracts.ApiItemDto): boolean { - return true; - } + public Render(options: PluginOptions): PluginResult { + const heading: string = options.Reference.Alias; + const pluginResult: PluginResult = { + ...GeneratorHelpers.GetDefaultPluginResultData(), + ApiItem: options.ApiItem, + Reference: options.Reference, + Headings: [ + { + Heading: heading, + ApiItemId: options.Reference.Id + } + ] + }; - public Render(data: PluginOptions): PluginResult { - const heading = data.Reference.Alias; - const headings: PluginHeading[] = [ - { - Heading: heading, - ApiItemId: data.Reference.Id - } - ]; - const typeStringDto = GeneratorHelpers.TypeDtoToMarkdownString(data.ApiItem.Type); + // Type + const typeStringDto = GeneratorHelpers.TypeDtoToMarkdownString(options.ApiItem.Type); - const builder = new MarkdownBuilder() - .Header(heading, 2) + pluginResult.Result = new MarkdownBuilder() + .Header(heading, 3) .EmptyLine() - .Text(GeneratorHelpers.RenderApiItemMetadata(data.ApiItem)) - .Code(GeneratorHelpers.ApiVariableToString(data.ApiItem), GeneratorHelpers.DEFAULT_CODE_OPTIONS) + .Text(GeneratorHelpers.RenderApiItemMetadata(options.ApiItem)) + .Code(GeneratorHelpers.ApiVariableToString(options.ApiItem), GeneratorHelpers.DEFAULT_CODE_OPTIONS) .EmptyLine() - .Header("Type", 3) + .Bold("Type") .EmptyLine() - .Text(typeStringDto.Text); + .Text(typeStringDto.Text) + .GetOutput(); - return { - ApiItem: data.ApiItem, - Reference: data.Reference, - Headings: headings, - Result: builder.GetOutput(), - UsedReferences: typeStringDto.References - }; + return pluginResult; } } 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 e28c11a5..19bb8c47 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,21 +5,345 @@ Array [ Object { "FileLocation": "index.md", "Result": Array [ - "[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-2]: index/earth.md#earth", + "[ClassDeclaration-1]: index/world.md#world", + "[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", "[ClassDeclaration-0]: index/foo.md#foo", "[ClassDeclaration-1]: index/world.md#world", "[ClassDeclaration-2]: index/earth.md#earth", - "[ClassDeclaration-2]: index/earth.md#earth", - "[ClassDeclaration-1]: index/world.md#world", "# index", "", - "## interface ExtendedBar", + "## Functions", + "", + "### AnotherFoo(parameter1, parameter2)", + "", + "\`\`\`typescript", + "function AnotherFoo(parameter1: string, parameter2: Promise): string", + "\`\`\`", + "", + "**Type parameters**", + "", + "| Name | Constraint type |", + "| ---- | --------------- |", + "| T | Object |", + "", + "**Parameters**", + "", + "| Name | Type |", + "| ---------- | -------------------- |", + "| parameter1 | string |", + "| parameter2 | Promise&\\\\#60;T&\\\\#62; |", + "", + "**Return type**", + "", + "string", + "", + "----------", + "", + "### GetFoo()", + "", + "\`\`\`typescript", + "function GetFoo(): Promise", + "\`\`\`", + "", + "**Return type**", + "", + "Promise<void>", + "", + "----------", + "", + "### FunctionWithOneParameter(parameter)", + "", + "\`\`\`typescript", + "function FunctionWithOneParameter(parameter: string): void", + "\`\`\`", + "", + "**Parameters**", + "", + "| Name | Type |", + "| --------- | ------ |", + "| parameter | string |", + "", + "**Return type**", + "", + "void", + "", + "----------", + "", + "### FunctionWithNoParameters()", + "", + "\`\`\`typescript", + "function FunctionWithNoParameters(): void", + "\`\`\`", + "", + "**Return type**", + "", + "void", + "", + "----------", + "", + "### FunctionWithMultipleParameters(parameter1, parameter2)", + "", + "\`\`\`typescript", + "function FunctionWithMultipleParameters(parameter1: string, parameter2: number): void", + "\`\`\`", + "", + "**Parameters**", + "", + "| Name | Type |", + "| ---------- | ------ |", + "| parameter1 | string |", + "| parameter2 | number |", + "", + "**Return type**", + "", + "void", + "", + "----------", + "", + "### Bar(parameter1, parameter2)", + "", + "Warning: Beta!", + "", + "Deprecated!", + "", + "Some general comment about Bar function.", + "", + "\`\`\`typescript", + "function Bar(parameter1: string, parameter2: number): string", + "\`\`\`", + "", + "**Parameters**", + "", + "| Name | Type |", + "| ---------- | ------ |", + "| parameter1 | string |", + "| parameter2 | number |", + "", + "**Return type**", + "", + "string", + "", + "----------", + "", + "### FunctionWithMultipleTypeParameters(parameter1, parameter2)", + "", + "Comment on Function with multiple type parameters.", + "", + "\`\`\`typescript", + "function FunctionWithMultipleTypeParameters(parameter1: T, parameter2: P): string", + "\`\`\`", + "", + "**Type parameters**", + "", + "| Name | Constraint type |", + "| ---- | --------------- |", + "| T | Object |", + "| P | |", + "", + "**Parameters**", + "", + "| Name | Type | Description |", + "| ---------- | ---- | --------------------- |", + "| parameter1 | T | Parameter one comment |", + "| parameter2 | P | Parameter two comment |", + "", + "**Return type**", + "", + "string", + "", + "----------", + "", + "### FunctionWithTypeParameterDefault(parameter1, parameter2)", + "", + "Some general comment about Function with type parameter default function.", + "", + "\`\`\`typescript", + "function FunctionWithTypeParameterDefault(parameter1: string, parameter2: T): string", + "\`\`\`", + "", + "**Type parameters**", + "", + "| Name | Constraint type | Default type |", + "| ---- | --------------- | ------------ |", + "| T | Object | {} |", + "", + "**Parameters**", + "", + "| Name | Type |", + "| ---------- | ------ |", + "| parameter1 | string |", + "| parameter2 | T |", + "", + "**Return type**", + "", + "string", + "", + "----------", + "", + "### FunctionWithTypeParameterConstraint(parameter1, parameter2)", + "", + "Some general comment about AnotherBar function.", + "", + "\`\`\`typescript", + "function FunctionWithTypeParameterConstraint(parameter1: string, parameter2: T): string", + "\`\`\`", + "", + "**Type parameters**", + "", + "| Name | Constraint type |", + "| ---- | --------------- |", + "| T | Object |", + "", + "**Parameters**", + "", + "| Name | Type |", + "| ---------- | ------ |", + "| parameter1 | string |", + "| parameter2 | T |", + "", + "**Return type**", + "", + "string", + "", + "----------", + "", + "### FunctionWithoutReturnType(parameter1, parameter2)", + "", + "\`\`\`typescript", + "function FunctionWithoutReturnType(parameter1: string, parameter2: Promise): string", + "\`\`\`", + "", + "**Type parameters**", + "", + "| Name | Constraint type |", + "| ---- | ---------------- |", + "| T | Array<T> |", + "", + "**Parameters**", + "", + "| Name | Type |", + "| ---------- | -------------------- |", + "| parameter1 | string |", + "| parameter2 | Promise&\\\\#60;T&\\\\#62; |", + "", + "**Return type**", + "", + "string", + "", + "----------", + "", + "### FunctionWithGenericReturnType()", + "", + "\`\`\`typescript", + "function FunctionWithGenericReturnType(): string[]", + "\`\`\`", + "", + "**Return type**", + "", + "Array<string>", + "", + "----------", + "", + "### FunctionWithPrimitiveReturnType()", + "", + "\`\`\`typescript", + "function FunctionWithPrimitiveReturnType(): boolean", + "\`\`\`", + "", + "**Return type**", + "", + "true | false", + "", + "----------", + "", + "### FunctionWithUnionReturnType()", + "", + "\`\`\`typescript", + "function FunctionWithUnionReturnType(): \\"something\\" | \\"nothing\\"", + "\`\`\`", + "", + "**Return type**", + "", + "\\"something\\" | \\"nothing\\"", + "", + "----------", + "", + "### FunctionWithIntersectionReturnType()", + "", + "\`\`\`typescript", + "function FunctionWithIntersectionReturnType(): Earth & World", + "\`\`\`", + "", + "**Return type**", + "", + "[Earth][ClassDeclaration-2] & [World][ClassDeclaration-1]", + "", + "----------", + "", + "### MyFunction()", + "", + "Function with TypeParameter as TypeLiteral.", + "", + "\`\`\`typescript", + "function MyFunction(): T", + "\`\`\`", + "", + "**Type parameters**", + "", + "| Name | Constraint type | Default type |", + "| ---- | ----------------------------------------------------------- | ----------------------- |", + "| T | { myProperty: string; myPropertyTwo?: number | undefined; } | { myProperty: string; } |", + "", + "**Return type**", + "", + "T", + "", + "----------", + "", + "### FunctionWithInitializedNumberParameter(someParameter)", + "", + "\`\`\`typescript", + "function FunctionWithInitializedNumberParameter(someParameter: number = 12): number", + "\`\`\`", + "", + "**Parameters**", + "", + "| Name | Type |", + "| ------------- | ------ |", + "| someParameter | number |", + "", + "**Return type**", + "", + "number", + "", + "----------", + "", + "### FunctionWithInitializedStringParameter(someParameter)", + "", + "\`\`\`typescript", + "function FunctionWithInitializedStringParameter(someParameter: string = \\"12\\"): string", + "\`\`\`", + "", + "**Parameters**", + "", + "| Name | Type |", + "| ------------- | ------ |", + "| someParameter | string |", + "", + "**Return type**", + "", + "string", + "", + "## Interfaces", + "", + "### ExtendedBar", "", "\`\`\`typescript", "interface ExtendedBar extends FooInterface, Boo {", @@ -27,19 +351,21 @@ Array [ "}", "\`\`\`", "", - "### Extends", + "**Extends**", "", "[FooInterface][InterfaceDeclaration-1]<number>", "", "[Boo][InterfaceDeclaration-2]", "", - "### Properties", + "**Properties**", "", "| Name | Type |", "| ---------- | --------------------- |", "| OtherStuff | Array<string> |", "", - "## interface FooInterface", + "----------", + "", + "### FooInterface", "", "\`\`\`typescript", "interface FooInterface {", @@ -49,13 +375,13 @@ Array [ "}", "\`\`\`", "", - "### Type parameters", + "**Type parameters**", "", "| Name |", "| ----- |", "| TType |", "", - "### Properties", + "**Properties**", "", "| Name | Type |", "| ------- | ------ |", @@ -63,7 +389,9 @@ Array [ "| Surname | string |", "| Type | TType |", "", - "## interface Boo", + "----------", + "", + "### Boo", "", "\`\`\`typescript", "interface Boo {", @@ -71,13 +399,15 @@ Array [ "}", "\`\`\`", "", - "### Properties", + "**Properties**", "", "| Name | Type |", "| ---- | --------------------- |", "| Boos | Array<string> |", "", - "## interface AnotherInterface", + "----------", + "", + "### AnotherInterface", "", "\`\`\`typescript", "interface AnotherInterface {", @@ -85,30 +415,32 @@ Array [ "}", "\`\`\`", "", - "### Call", + "#### Call", "", "\`\`\`typescript", "(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", + "----------", + "", + "### MyConstraintType", "", "\`\`\`typescript", "interface MyConstraintType {", @@ -116,13 +448,15 @@ Array [ "}", "\`\`\`", "", - "### Properties", + "**Properties**", "", "| Name | Type |", "| ---------- | ------ |", "| myProperty | string |", "", - "## interface MyDefaultType", + "----------", + "", + "### MyDefaultType", "", "\`\`\`typescript", "interface MyDefaultType extends MyConstraintType {", @@ -130,17 +464,19 @@ Array [ "}", "\`\`\`", "", - "### Extends", + "**Extends**", "", "[MyConstraintType][InterfaceDeclaration-4]", "", - "### Properties", + "**Properties**", "", "| Name | Type |", "| --------------- | ------ |", "| anotherProperty | number |", "", - "## interface ObjectsInterface", + "----------", + "", + "### ObjectsInterface", "", "\`\`\`typescript", "interface ObjectsInterface {", @@ -149,14 +485,16 @@ Array [ "}", "\`\`\`", "", - "### Properties", + "**Properties**", "", "| Name | Type |", "| --------- | ------ |", "| objectOne | Object |", "| objectTwo | Object |", "", - "## interface InterfaceWithCall", + "----------", + "", + "### InterfaceWithCall", "", "\`\`\`typescript", "interface InterfaceWithCall {", @@ -164,23 +502,25 @@ Array [ "}", "\`\`\`", "", - "### Call", + "#### Call", "", "\`\`\`typescript", "(): { someProperty: T; }", "\`\`\`", "", - "**Type parameters:**", + "**Type parameters**", "", "| Name |", "| ---- |", "| T |", "", - "**Return type:**", + "**Return type**", "", "{ someProperty: T; }", "", - "## interface InterfaceWithConstraintType", + "----------", + "", + "### InterfaceWithConstraintType", "", "\`\`\`typescript", "interface InterfaceWithConstraintType extends Dictionary {", @@ -188,17 +528,19 @@ Array [ "}", "\`\`\`", "", - "### Extends", + "**Extends**", "", "[Dictionary][InterfaceDeclaration-9]<string>", "", - "### Properties", + "**Properties**", "", "| Name | Type |", "| ------------ | ------ |", "| someProperty | string |", "", - "## interface InterfaceWithMethod", + "----------", + "", + "### InterfaceWithMethod", "", "\`\`\`typescript", "interface InterfaceWithMethod {", @@ -207,19 +549,19 @@ Array [ "}", "\`\`\`", "", - "### Type parameters", + "**Type parameters**", "", "| Name |", "| ---- |", "| T |", "", - "### Methods", + "#### Methods", "", "\`\`\`typescript", "someMethodOne(): T", "\`\`\`", "", - "**Return type:**", + "**Return type**", "", "T", "", @@ -227,17 +569,19 @@ Array [ "someMethodTwo(): TReturn", "\`\`\`", "", - "**Type parameters:**", + "**Type parameters**", "", "| Name |", "| ------- |", "| TReturn |", "", - "**Return type:**", + "**Return type**", "", "TReturn", "", - "## interface Dictionary", + "----------", + "", + "### Dictionary", "", "\`\`\`typescript", "interface Dictionary {", @@ -246,33 +590,34 @@ Array [ "}", "\`\`\`", "", - "### Type parameters", + "**Type parameters**", "", "| Name |", "| ------ |", "| TValue |", "", - "### Construct", + "#### Construct", "", "\`\`\`typescript", "new (): Dictionary", "\`\`\`", "", - "**Return type:**", + "**Return type**", "", "[Dictionary][InterfaceDeclaration-9]<TValue>", "", - "### Index signatures", + "#### Index signatures", "", "\`\`\`typescript", "[key: string]: TValue", "\`\`\`", "", - "Index \`key\` - string", + "* *Parameter* \`key\` - string", + "* *Type* TValue", "", - "Type - TValue", + "----------", "", - "## interface MethodsInterface", + "### MethodsInterface", "", "\`\`\`typescript", "interface MethodsInterface {", @@ -281,45 +626,47 @@ Array [ "}", "\`\`\`", "", - "### Call", + "#### Call", "", "\`\`\`typescript", "(arg: TValue): void", "\`\`\`", "", - "**Type parameters:**", + "**Type parameters**", "", "| Name |", "| ------ |", "| TValue |", "", - "**Parameters:**", + "**Parameters**", "", "| Name | Type |", "| ---- | ------ |", "| arg | TValue |", "", - "**Return type:**", + "**Return type**", "", "void", "", - "### Methods", + "#### Methods", "", "\`\`\`typescript", "someMethod(): string", "\`\`\`", "", - "**Type parameters:**", + "**Type parameters**", "", "| Name |", "| ---- |", "| T |", "", - "**Return type:**", + "**Return type**", "", "string", "", - "## interface MonsterInterface", + "----------", + "", + "### MonsterInterface", "", "Warning: Beta!", "", @@ -340,29 +687,29 @@ Array [ "}", "\`\`\`", "", - "### Type parameters", + "**Type parameters**", "", "| Name | Constraint type | Default type |", "| ------ | --------------- | ------------ |", - "| TValue | Object | \\\\{\\\\} |", + "| TValue | Object | {} |", "", - "### Extends", + "**Extends**", "", "[ObjectsInterface][InterfaceDeclaration-6]", "", - "### Construct", + "#### Construct", "", "\`\`\`typescript", "new (): MonsterInterface", "\`\`\`", "", - "**Type parameters:**", + "**Type parameters**", "", "| Name |", "| ---- |", "| T |", "", - "**Return type:**", + "**Return type**", "", "[MonsterInterface][InterfaceDeclaration-12]<T>", "", @@ -370,29 +717,29 @@ Array [ "new (someParameter: string): string", "\`\`\`", "", - "**Parameters:**", + "**Parameters**", "", "| Name | Type |", "| ------------- | ------ |", "| someParameter | string |", "", - "**Return type:**", + "**Return type**", "", "string", "", - "### Call", + "#### Call", "", "\`\`\`typescript", "(): { someProperty: T; }", "\`\`\`", "", - "**Type parameters:**", + "**Type parameters**", "", "| Name |", "| ---- |", "| T |", "", - "**Return type:**", + "**Return type**", "", "{ someProperty: T; }", "", @@ -400,19 +747,19 @@ Array [ "(key?: string | undefined): { someProperty: T; }", "\`\`\`", "", - "**Type parameters:**", + "**Type parameters**", "", "| Name |", "| ---- |", "| T |", "", - "**Parameters:**", + "**Parameters**", "", - "| Name | Type | Optional |", - "| ---- | ----------------------- | -------- |", - "| key | undefined | string | Yes |", + "| Name | Type |", + "| ---- | ----------------------- |", + "| key | undefined | string |", "", - "**Return type:**", + "**Return type**", "", "{ someProperty: T; }", "", @@ -420,42 +767,41 @@ Array [ "(key: number): { someProperty: T; }", "\`\`\`", "", - "**Type parameters:**", + "**Type parameters**", "", "| Name |", "| ---- |", "| T |", "", - "**Parameters:**", + "**Parameters**", "", "| Name | Type |", "| ---- | ------ |", "| key | number |", "", - "**Return type:**", + "**Return type**", "", "{ someProperty: T; }", "", - "### Index signatures", + "#### Index signatures", "", "\`\`\`typescript", "readonly [key: string]: TValue", "\`\`\`", "", - "Readonly.", - "", - "Index \`key\` - string", + "* *Parameter* \`key\` - string", + "* *Type* TValue", "", - "Type - TValue", - "", - "### Properties", + "**Properties**", "", "| Name | Type |", "| --------- | ------ |", "| objectOne | TValue |", "| objectTwo | TValue |", "", - "## interface SomeInterface", + "----------", + "", + "### SomeInterface", "", "\`\`\`typescript", "interface SomeInterface {", @@ -464,25 +810,25 @@ Array [ "}", "\`\`\`", "", - "### Index signatures", + "#### Index signatures", "", "\`\`\`typescript", "[key: string]: string | number", "\`\`\`", "", - "Index \`key\` - string", - "", - "Type - string | number", + "* *Parameter* \`key\` - string", + "* *Type* string | number", "", "\`\`\`typescript", "[key: number]: string", "\`\`\`", "", - "Index \`key\` - number", + "* *Parameter* \`key\` - number", + "* *Type* string", "", - "Type - string", + "----------", "", - "## interface StringsDictionary", + "### StringsDictionary", "", "\`\`\`typescript", "interface StringsDictionary {", @@ -490,17 +836,18 @@ Array [ "}", "\`\`\`", "", - "### Index signatures", + "#### Index signatures", "", "\`\`\`typescript", "[key: string]: string", "\`\`\`", "", - "Index \`key\` - string", + "* *Parameter* \`key\` - string", + "* *Type* string", "", - "Type - string", + "----------", "", - "## interface MyInterface", + "### MyInterface", "", "\`\`\`typescript", "interface MyInterface {", @@ -510,7 +857,7 @@ Array [ "}", "\`\`\`", "", - "### Properties", + "**Properties**", "", "| Name | Type |", "| --------------- | ------ |", @@ -518,7 +865,9 @@ Array [ "| MyPropertyTwo | Object |", "| MyPropertyThree | number |", "", - "## EnumList", + "## Enums", + "", + "### EnumList", "", "Simple list.", "", @@ -531,13 +880,17 @@ Array [ "}", "\`\`\`", "", + "**Members**", + "", "| Name | Value | Description |", "| ------------ | ----- | ------------------------------ |", "| FirstOption | 0 | Description for First option. |", "| SecondOption | 1 | Description for Second option. |", "| ThirdOption | 2 | Description for Third option. |", "", - "## EnumListWithNumberValues", + "----------", + "", + "### EnumListWithNumberValues", "", "List with number values with no punctuation at the end of description", "", @@ -550,13 +903,17 @@ Array [ "}", "\`\`\`", "", + "**Members**", + "", "| Name | Value |", "| ------------ | ----- |", "| FirstOption | 1 |", "| SecondOption | 2 |", "| ThirdOption | 3 |", "", - "## EnumListWithStringValues", + "----------", + "", + "### EnumListWithStringValues", "", "Warning: Beta!", "", @@ -571,334 +928,39 @@ Array [ "}", "\`\`\`", "", + "**Members**", + "", "| Name | Value |", "| ------------ | -------- |", "| FirstOption | \\"first\\" |", "| SecondOption | \\"second\\" |", "| ThirdOption | \\"third\\" |", "", - "## SampleConst", - "", - "\`\`\`typescript", - "const SampleConst: string;", - "\`\`\`", - "", - "### Type", - "", - "string", - "", - "## [Foo][ClassDeclaration-0]", - "", - "## [World][ClassDeclaration-1]", - "", - "## [Earth][ClassDeclaration-2]", - "", - "## AnotherFoo(parameter1, parameter2)", - "", - "\`\`\`typescript", - "function AnotherFoo(parameter1: string, parameter2: Promise): string", - "\`\`\`", - "", - "### Type parameters", - "", - "| Name | Constraint type |", - "| ---- | --------------- |", - "| T | Object |", - "", - "### Parameters", - "", - "| Name | Type |", - "| ---------- | -------------------- |", - "| parameter1 | string |", - "| parameter2 | Promise&\\\\#60;T&\\\\#62; |", - "", - "### Return type", - "", - "string", - "", - "", - "## GetFoo()", - "", - "\`\`\`typescript", - "function GetFoo(): Promise", - "\`\`\`", - "", - "### Return type", - "", - "Promise<void>", - "", - "", - "## FunctionWithOneParameter(parameter)", - "", - "\`\`\`typescript", - "function FunctionWithOneParameter(parameter: string): void", - "\`\`\`", - "", - "### Parameters", - "", - "| Name | Type |", - "| --------- | ------ |", - "| parameter | string |", - "", - "### Return type", - "", - "void", - "", - "", - "## FunctionWithNoParameters()", - "", - "\`\`\`typescript", - "function FunctionWithNoParameters(): void", - "\`\`\`", - "", - "### Return type", - "", - "void", - "", - "", - "## FunctionWithMultipleParameters(parameter1, parameter2)", - "", - "\`\`\`typescript", - "function FunctionWithMultipleParameters(parameter1: string, parameter2: number): void", - "\`\`\`", - "", - "### Parameters", - "", - "| Name | Type |", - "| ---------- | ------ |", - "| parameter1 | string |", - "| parameter2 | number |", - "", - "### Return type", - "", - "void", - "", - "", - "## Bar(parameter1, parameter2)", - "", - "Warning: Beta!", - "", - "Deprecated!", - "", - "Some general comment about Bar function.", - "", - "\`\`\`typescript", - "function Bar(parameter1: string, parameter2: number): string", - "\`\`\`", - "", - "### Parameters", - "", - "| Name | Type |", - "| ---------- | ------ |", - "| parameter1 | string |", - "| parameter2 | number |", - "", - "### Return type", - "", - "string", - "", - "", - "## FunctionWithMultipleTypeParameters(parameter1, parameter2)", - "", - "Comment on Function with multiple type parameters.", - "", - "\`\`\`typescript", - "function FunctionWithMultipleTypeParameters(parameter1: T, parameter2: P): string", - "\`\`\`", - "", - "### Type parameters", - "", - "| Name | Constraint type |", - "| ---- | --------------- |", - "| T | Object |", - "| P | |", - "", - "### Parameters", + "## Classes", "", - "| Name | Type |", - "| ---------- | ---- |", - "| parameter1 | T |", - "| parameter2 | P |", + "### [Foo][ClassDeclaration-0]", "", - "### Return type", + "----------", "", - "string", - "", - "", - "## FunctionWithTypeParameterDefault(parameter1, parameter2)", - "", - "Some general comment about Function with type parameter default function.", - "", - "\`\`\`typescript", - "function FunctionWithTypeParameterDefault(parameter1: string, parameter2: T): string", - "\`\`\`", - "", - "### Type parameters", - "", - "| Name | Constraint type | Default type |", - "| ---- | --------------- | ------------ |", - "| T | Object | \\\\{\\\\} |", - "", - "### Parameters", - "", - "| Name | Type |", - "| ---------- | ------ |", - "| parameter1 | string |", - "| parameter2 | T |", - "", - "### Return type", - "", - "string", - "", - "", - "## FunctionWithTypeParameterConstraint(parameter1, parameter2)", - "", - "Some general comment about AnotherBar function.", - "", - "\`\`\`typescript", - "function FunctionWithTypeParameterConstraint(parameter1: string, parameter2: T): string", - "\`\`\`", - "", - "### Type parameters", - "", - "| Name | Constraint type |", - "| ---- | --------------- |", - "| T | Object |", - "", - "### Parameters", - "", - "| Name | Type |", - "| ---------- | ------ |", - "| parameter1 | string |", - "| parameter2 | T |", - "", - "### Return type", - "", - "string", - "", - "", - "## FunctionWithoutReturnType(parameter1, parameter2)", - "", - "\`\`\`typescript", - "function FunctionWithoutReturnType(parameter1: string, parameter2: Promise): string", - "\`\`\`", - "", - "### Type parameters", - "", - "| Name | Constraint type |", - "| ---- | ------------------ |", - "| T | Array&\\\\#60;T&\\\\#62; |", - "", - "### Parameters", - "", - "| Name | Type |", - "| ---------- | -------------------- |", - "| parameter1 | string |", - "| parameter2 | Promise&\\\\#60;T&\\\\#62; |", + "### [World][ClassDeclaration-1]", "", - "### Return type", + "----------", "", - "string", + "### [Earth][ClassDeclaration-2]", "", + "## Variables", "", - "## FunctionWithGenericReturnType()", + "### SampleConst", "", "\`\`\`typescript", - "function FunctionWithGenericReturnType(): string[]", - "\`\`\`", - "", - "### Return type", - "", - "Array<string>", - "", - "", - "## FunctionWithPrimitiveReturnType()", - "", - "\`\`\`typescript", - "function FunctionWithPrimitiveReturnType(): boolean", - "\`\`\`", - "", - "### Return type", - "", - "true | false", - "", - "", - "## FunctionWithUnionReturnType()", - "", - "\`\`\`typescript", - "function FunctionWithUnionReturnType(): \\"something\\" | \\"nothing\\"", - "\`\`\`", - "", - "### Return type", - "", - "\\"something\\" | \\"nothing\\"", - "", - "", - "## FunctionWithIntersectionReturnType()", - "", - "\`\`\`typescript", - "function FunctionWithIntersectionReturnType(): Earth & World", - "\`\`\`", - "", - "### Return type", - "", - "[Earth][ClassDeclaration-2] & [World][ClassDeclaration-1]", - "", - "", - "## MyFunction()", - "", - "Function with TypeParameter as TypeLiteral.", - "", - "\`\`\`typescript", - "function MyFunction(): T", - "\`\`\`", - "", - "### Type parameters", - "", - "| Name | Constraint type | Default type |", - "| ---- | ------------------------------------------------------------------ | ------------------------- |", - "| T | \\\\{ myProperty: string; myPropertyTwo?: number | undefined; \\\\} | \\\\{ myProperty: string; \\\\} |", - "", - "### Return type", - "", - "T", - "", - "", - "## FunctionWithInitializedNumberParameter(someParameter)", - "", - "\`\`\`typescript", - "function FunctionWithInitializedNumberParameter(someParameter: number = 12): number", - "\`\`\`", - "", - "### Parameters", - "", - "| Name | Type | Initial value |", - "| ------------- | ------ | ------------- |", - "| someParameter | number | 12 |", - "", - "### Return type", - "", - "number", - "", - "", - "## FunctionWithInitializedStringParameter(someParameter)", - "", - "\`\`\`typescript", - "function FunctionWithInitializedStringParameter(someParameter: string = \\"12\\"): string", + "const SampleConst: string;", "\`\`\`", "", - "### Parameters", - "", - "| Name | Type | Initial value |", - "| ------------- | ------ | ------------- |", - "| someParameter | string | \\"12\\" |", - "", - "### Return type", + "**Type**", "", "string", "", "", - "", ], }, Object { @@ -916,12 +978,16 @@ Array [ "\`\`\`typescript", "public HandleMessage(message: string): string", "\`\`\`", - "#### Parameters", + "", + "**Parameters**", "", "| Name | Type |", "| ------- | ------ |", "| message | string |", "", + "**Return type**", + "", + "string", "", "", ], diff --git a/packages/ts-docs-gen/tests/cases/__tests__/__snapshots__/simple-project-2.test.ts.snap b/packages/ts-docs-gen/tests/cases/__tests__/__snapshots__/simple-project-2.test.ts.snap index a00154f2..376c2325 100644 --- a/packages/ts-docs-gen/tests/cases/__tests__/__snapshots__/simple-project-2.test.ts.snap +++ b/packages/ts-docs-gen/tests/cases/__tests__/__snapshots__/simple-project-2.test.ts.snap @@ -9,9 +9,13 @@ Array [ "[ClassDeclaration-1]: index/foostart.md#foostart", "# index", "", - "## [Foo][ClassDeclaration-0]", + "## Classes", "", - "## [FooStart][ClassDeclaration-1]", + "### [Foo][ClassDeclaration-0]", + "", + "----------", + "", + "### [FooStart][ClassDeclaration-1]", "", "", ], @@ -31,12 +35,16 @@ Array [ "\`\`\`typescript", "public GetMessage(message: string): string", "\`\`\`", - "#### Parameters", + "", + "**Parameters**", "", "| Name | Type |", "| ------- | ------ |", "| message | string |", "", + "**Return type**", + "", + "string", "", "## Properties", "", @@ -46,7 +54,7 @@ Array [ "private readonly defaultMessage: string;", "\`\`\`", "", - "### Type", + "**Type**", "", "string", "", @@ -68,12 +76,16 @@ Array [ "\`\`\`typescript", "public HandleMessage(message: string): string", "\`\`\`", - "#### Parameters", + "", + "**Parameters**", "", "| Name | Type |", "| ------- | ------ |", "| message | string |", "", + "**Return type**", + "", + "string", "", "", ], @@ -84,7 +96,9 @@ Array [ "[ClassDeclaration-0]: index/foo.md#foo", "# foo", "", - "## [Foo][ClassDeclaration-0]", + "## Classes", + "", + "### [Foo][ClassDeclaration-0]", "", "", ],