From 2d9aa1ec74adca3b00f75bee1bc0a5cb4a713875 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Fri, 8 Dec 2017 18:29:59 +0200 Subject: [PATCH 01/26] GetApiItemsFromReferenceTuple helper added. --- packages/ts-docs-gen/src/extractor-helpers.ts | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/packages/ts-docs-gen/src/extractor-helpers.ts b/packages/ts-docs-gen/src/extractor-helpers.ts index c5bd13d7..41dbbaaa 100644 --- a/packages/ts-docs-gen/src/extractor-helpers.ts +++ b/packages/ts-docs-gen/src/extractor-helpers.ts @@ -100,4 +100,22 @@ export namespace ExtractorHelpers { return trimmedSentence + punctuationMark; } + + export function GetApiItemsFromReferenceTuple( + items: Contracts.ApiItemReferenceTuple, + extractedData: ExtractDto + ): T[] { + const apiItems: T[] = []; + + for (const itemReferences of items) { + const [, references] = itemReferences; + + for (const reference of references) { + const apiItem = extractedData.Registry[reference] as T; + apiItems.push(apiItem); + } + } + + return apiItems; + } } From 1686625e52e1062d9edb7d12b7a64d2174da3f92 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Fri, 8 Dec 2017 18:30:36 +0200 Subject: [PATCH 02/26] Helper used int ApiEnumPlugin. --- .../src/plugins/api-enum-plugin.ts | 28 ++++++------------- 1 file changed, 8 insertions(+), 20 deletions(-) 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 4b9a31a8..867ba737 100644 --- a/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts @@ -1,4 +1,4 @@ -import { Contracts, ExtractDto } from "ts-extractor"; +import { Contracts } from "ts-extractor"; import { MarkdownGenerator, MarkdownBuilder } from "@simplrjs/markdown"; import { ApiItemPluginBase } from "../abstractions/api-item-plugin-base"; @@ -8,6 +8,7 @@ import { RenderItemOutputDto } from "../contracts/render-item-output-dto"; import { ExtractorHelpers } from "../extractor-helpers"; // TODO: const enums implementation. +// TODO: add summary jsdoc support. export class ApiEnumPlugin extends ApiItemPluginBase { public SupportedApiItemsKinds(): SupportedApiItemKindType[] { return [this.SupportKind.Enum]; @@ -38,6 +39,7 @@ export class ApiEnumPlugin extends ApiItemPluginBase { }); } + // TODO: simplify. Markdown removes empty columns automatically. private constructEnumTable(members: Contracts.ApiEnumMemberDto[]): string[] { // Table header. const header = ["Name", "Value"]; @@ -80,26 +82,12 @@ export class ApiEnumPlugin extends ApiItemPluginBase { return MarkdownGenerator.Table(header, content); } - /** - * Resolve api items of an enum from ApiItemReferenceTuple. - */ - private getEnumMembers(members: Contracts.ApiItemReferenceTuple, extractedData: ExtractDto): Contracts.ApiEnumMemberDto[] { - const apiItems: Contracts.ApiEnumMemberDto[] = []; - - for (const memberReferences of members) { - const [, references] = memberReferences; - for (const reference of references) { - const apiItem = extractedData.Registry[reference] as Contracts.ApiEnumMemberDto; - apiItems.push(apiItem); - } - } - - return apiItems; - } - public Render(data: PluginData): RenderItemOutputDto { const [, alias] = data.Reference; - const enumMembers = this.getEnumMembers(data.ApiItem.Members, data.ExtractedData); + const enumMembers = ExtractorHelpers.GetApiItemsFromReferenceTuple( + data.ApiItem.Members, + data.ExtractedData + ); const builder = new MarkdownBuilder() .Header(alias, 2) .EmptyLine() @@ -112,7 +100,7 @@ export class ApiEnumPlugin extends ApiItemPluginBase { .Text(this.constructEnumTable(enumMembers)); return { - Heading: "Enum", + Heading: alias, ApiItem: data.ApiItem, References: [], RenderOutput: builder.GetOutput() From 7511b1523c0b3608142e88c087dff5aeb5c19b6e Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Fri, 8 Dec 2017 18:32:20 +0200 Subject: [PATCH 03/26] Type to String helpers added. --- packages/ts-docs-gen/src/generator-helpers.ts | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/packages/ts-docs-gen/src/generator-helpers.ts b/packages/ts-docs-gen/src/generator-helpers.ts index 4e01ecc8..923e454c 100644 --- a/packages/ts-docs-gen/src/generator-helpers.ts +++ b/packages/ts-docs-gen/src/generator-helpers.ts @@ -63,4 +63,79 @@ export namespace GeneratorHelpers { Text: text }; } + + export function TypeDtoToString(type: Contracts.TypeDto): string { + let text: string = ""; + + switch (type.ApiTypeKind) { + case Contracts.TypeKinds.Union: + case Contracts.TypeKinds.Intersection: { + const symbol = type.ApiTypeKind === Contracts.TypeKinds.Union ? "|" : "&"; + + type.Types + .map(TypeDtoToString) + .forEach(typeString => { + if (text === "") { + text = typeString; + } else { + text += ` ${symbol} ${typeString}`; + } + }); + break; + } + case Contracts.TypeKinds.Reference: { + text = type.Name || "???"; + + // Generics + if (type.Generics != null) { + const generics = type.Generics.map(TypeDtoToString); + + text += `<${generics.join(", ")}>`; + } + break; + } + case Contracts.TypeKinds.Basic: + default: { + text = type.Name || type.Text; + + // Generics + if (type.Name != null && type.Generics != null) { + const generics = type.Generics.map(TypeDtoToString); + + text += `<${generics.join(", ")}>`; + } + } + } + + return text; + } + + export function TypeParameterToString(typeParameter: Contracts.ApiTypeParameterDto): string { + let output = typeParameter.Name; + + if (typeParameter.ConstraintType != null) { + output += ` extends ${TypeDtoToString(typeParameter.ConstraintType)}`; + } + + if (typeParameter.DefaultType != null) { + output += ` = ${TypeDtoToString(typeParameter.DefaultType)}`; + } + + return output; + } + + // TODO: implement. + export function TypeParameterToMarkdownString(typeParameter: Contracts.ApiTypeParameterDto): string { + let output = typeParameter.Name; + + if (typeParameter.ConstraintType != null) { + output += ` extends ${TypeDtoToString(typeParameter.ConstraintType)}`; + } + + if (typeParameter.DefaultType != null) { + output += ` = ${TypeDtoToString(typeParameter.DefaultType)}`; + } + + return output; + } } From 8b9046956ff79298e563f002ce9e03566bb05934 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Fri, 8 Dec 2017 18:32:42 +0200 Subject: [PATCH 04/26] ApiFunctionPlugin structure added. --- .../src/plugins/api-function-plugin.ts | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 packages/ts-docs-gen/src/plugins/api-function-plugin.ts diff --git a/packages/ts-docs-gen/src/plugins/api-function-plugin.ts b/packages/ts-docs-gen/src/plugins/api-function-plugin.ts new file mode 100644 index 00000000..4a7a636d --- /dev/null +++ b/packages/ts-docs-gen/src/plugins/api-function-plugin.ts @@ -0,0 +1,116 @@ +import { Contracts } from "ts-extractor"; +import { MarkdownBuilder } from "@simplrjs/markdown"; + +import { ApiItemPluginBase } from "../abstractions/api-item-plugin-base"; +import { SupportedApiItemKindType } from "../contracts/supported-api-item-kind-type"; +import { RenderItemOutputDto } from "../contracts/render-item-output-dto"; +import { PluginData } from "../contracts/plugin-data"; +import { GeneratorHelpers } from "../generator-helpers"; +import { ExtractorHelpers } from "../extractor-helpers"; + +export class ApiFunctionPlugin extends ApiItemPluginBase { + public SupportedApiItemsKinds(): SupportedApiItemKindType[] { + return [this.SupportKind.Function]; + } + + private resolveFunctionHeader( + alias: string, + parametersApiItems: Contracts.ApiParameterDto[], + typeParametersApiItems: Contracts.ApiTypeParameterDto[], + apiItem: Contracts.ApiFunctionDto + ): string { + let functionHeader = `function ${apiItem.Name}`; + + // Resolving type parameters + if (typeParametersApiItems.length > 0) { + const typeParameters = typeParametersApiItems + .map(GeneratorHelpers.TypeParameterToString) + .join(", "); + + functionHeader += `<${typeParameters}>`; + } + + // Resolving parameters + const parametersString = parametersApiItems + .map(parameter => `${parameter.Name}: ${GeneratorHelpers.TypeDtoToString(parameter.Type)}`) + .join(", "); + + functionHeader += `(${parametersString})`; + + // Resolving return type + // Ask @Martynas for cases where function have no return type. + if (apiItem.ReturnType != null) { + functionHeader += ": " + GeneratorHelpers.TypeDtoToString(apiItem.ReturnType); + } + + return functionHeader; + } + + private resolveDocumentationComment(metaData: Contracts.ApiMetadataDto): string[] { + if (metaData.DocumentationComment.length === 0) { + return []; + } + + // TODO: implement ExtractorHelpers.FixSentence when comments separation implemented in `ts-extractor`. + return metaData.DocumentationComment.map(commentItem => commentItem.text); + } + + // private resolveFunctionParameters(): string[] { + // const builder = new MarkdownBuilder(); + // return builder.GetOutput(); + // } + + private resolveFunctionTypeParameters(typeParameters: Contracts.ApiTypeParameterDto[]): string[] { + const builder = new MarkdownBuilder(); + + // typeParameters.map(parameter => { + // console.log(parameter); + // }); + + return builder.GetOutput(); + } + + public Render(data: PluginData): RenderItemOutputDto { + const [, alias] = data.Reference; + const parameters = ExtractorHelpers.GetApiItemsFromReferenceTuple( + data.ApiItem.Parameters, + data.ExtractedData + ); + + console.log(data.ApiItem.Metadata); + + const typeParameters = ExtractorHelpers.GetApiItemsFromReferenceTuple( + data.ApiItem.TypeParameters, + data.ExtractedData + ); + + const headerString = this.resolveFunctionHeader(alias, parameters, typeParameters, data.ApiItem); + const builder = new MarkdownBuilder() + .Header(headerString, 2) + .EmptyLine() + .Text(this.resolveDocumentationComment(data.ApiItem.Metadata)) + .EmptyLine() + .Text("TODO: is deprecated or beta") + .EmptyLine() + .Header("Type parameters", 3) + .EmptyLine() + .Text(this.resolveFunctionTypeParameters(typeParameters)) + .EmptyLine() + .Header("Parameters", 3) + .EmptyLine() + .Text("TODO") + .EmptyLine() + .Header("Return type", 3); + + // const returnTypeDto = GeneratorHelpers.TypeDtoToMarkdownString(data.ApiItem.ReturnType!); + // console.log(returnTypeDto); + + return { + Heading: alias, + ApiItem: data.ApiItem, + References: [], + RenderOutput: builder.GetOutput() + }; + } + +} From 684e6536d4c5959c42e4cd1fa0a90a2eb6bdbafc Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Fri, 8 Dec 2017 18:33:08 +0200 Subject: [PATCH 05/26] Default plugin added to DefaultPlugins. --- packages/ts-docs-gen/src/default-plugins.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/ts-docs-gen/src/default-plugins.ts b/packages/ts-docs-gen/src/default-plugins.ts index a291cba3..8a765ae7 100644 --- a/packages/ts-docs-gen/src/default-plugins.ts +++ b/packages/ts-docs-gen/src/default-plugins.ts @@ -1,7 +1,9 @@ import { ApiVariablePlugin } from "./plugins/api-variable-plugin"; import { ApiEnumPlugin } from "./plugins/api-enum-plugin"; +import { ApiFunctionPlugin } from "./plugins/api-function-plugin"; export const DefaultPlugins = [ new ApiVariablePlugin(), - new ApiEnumPlugin() + new ApiEnumPlugin(), + new ApiFunctionPlugin() ]; From f52b01102767a22d4f30ec217c4a0352c406588e Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Fri, 8 Dec 2017 18:33:38 +0200 Subject: [PATCH 06/26] Function examples added to `index.ts`. --- .../simple/docs/api/exported-functions.md | 30 ++- .../examples/simple/docs/api/index.md | 204 +++++++++++++++++- packages/ts-docs-gen/examples/simple/index.ts | 94 +++++++- 3 files changed, 317 insertions(+), 11 deletions(-) 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 6b8e6e49..1c454f4a 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,5 +1,31 @@ # exported-functions -## function: Foo +## function Foo(): string -## function: Bar + +TODO: is deprecated or beta + +### Type parameters + +TODO + +### Parameters + +TODO + +### Return type + +## function Bar(): string + + +TODO: is deprecated or beta + +### Type parameters + +TODO + +### Parameters + +TODO + +### Return type 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 8c08ae16..f3df24f2 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index.md @@ -1,12 +1,214 @@ # index +## class: World + +## class: Earth + +## function FunctionWithTypeParameterDefault(parameter1: string, parameter2: T): string + +Some general comment about AnotherBar function. + +TODO: is deprecated or beta + +### Type parameters + +TODO + +### Parameters + +TODO + +### Return type + +## function FunctionWithTypeParameterConstraint(parameter1: string, parameter2: T): string + +Some general comment about AnotherBar function. + +TODO: is deprecated or beta + +### Type parameters + +TODO + +### Parameters + +TODO + +### Return type + +## function AnotherFoo>(parameter1: string, parameter2: Promise): string + + +TODO: is deprecated or beta + +### Type parameters + +TODO + +### Parameters + +TODO + +### Return type + +## function FunctionWithOneParameter(parameter: string): void + + +TODO: is deprecated or beta + +### Type parameters + +TODO + +### Parameters + +TODO + +### Return type + +## function FunctionWithNoParameters(): void + + +TODO: is deprecated or beta + +### Type parameters + +TODO + +### Parameters + +TODO + +### Return type + +## function FunctionWithMultipleParameters(parameter1: string, parameter2: number): void + + +TODO: is deprecated or beta + +### Type parameters + +TODO + +### Parameters + +TODO + +### Return type + +## function Foo(): string + + +TODO: is deprecated or beta + +### Type parameters + +TODO + +### Parameters + +TODO + +### Return type + +## function Bar(parameter1: string, parameter2: number): string + +Some general comment about Bar function. + +TODO: is deprecated or beta + +### Type parameters + +TODO + +### Parameters + +TODO + +### Return type + +## function FunctionWithoutReturnType>(parameter1: string, parameter2: Promise): string + + +TODO: is deprecated or beta + +### Type parameters + +TODO + +### Parameters + +TODO + +### Return type + +## function FunctionWithGenericReturnType(): Array + + +TODO: is deprecated or beta + +### Type parameters + +TODO + +### Parameters + +TODO + +### Return type + +## function FunctionWithPrimitiveReturnType(): true | false + + +TODO: is deprecated or beta + +### Type parameters + +TODO + +### Parameters + +TODO + +### Return type + +## function FunctionWithUnionReturnType(): "something" | "nothing" + + +TODO: is deprecated or beta + +### Type parameters + +TODO + +### Parameters + +TODO + +### Return type + +## function FunctionWithIntersectionReturnType(): Earth & World + + +TODO: is deprecated or beta + +### Type parameters + +TODO + +### Parameters + +TODO + +### Return type + ## Uogos Some information 2nd line of some information 3rd line of some information 4th line of some information -5th line of some information. +5th line of some information deprecated beta diff --git a/packages/ts-docs-gen/examples/simple/index.ts b/packages/ts-docs-gen/examples/simple/index.ts index 63042ba2..6d835cef 100644 --- a/packages/ts-docs-gen/examples/simple/index.ts +++ b/packages/ts-docs-gen/examples/simple/index.ts @@ -2,20 +2,98 @@ // import { Foo } from "./exported-functions"; -// export class World { } -// export class Earth { } +export class World { } +export class Earth { } // export declare const Hello: World & Earth; // export const FooFunc = Foo; -// export function Foo(): string { -// return "foo"; -// } +//--------------------------------------------------------- -// export function Bar(): string { -// return "bar"; -// } +// #region Type parameters (generics) +// /** +// * Some general comment about function. + +/** + * Bla bla + * + * @template T something wwegweg + * @template P something wegweg + * @param parameter1 wegweg + * @param parameter2 wegweweg + * @returns wegweg + */ +export function FunctionWithMultipleTypeParameters(parameter1: T, parameter2: P): string { + return "bar"; +} + +/** + * Some general comment about AnotherBar function. + */ +export function FunctionWithTypeParameterDefault(parameter1: string, parameter2: T): string { + return "bar"; +} + +/** + * Some general comment about AnotherBar function. + */ +export function FunctionWithTypeParameterConstraint(parameter1: string, parameter2: T): string { + return "bar"; +} + +export function AnotherFoo>(parameter1: string, parameter2: Promise): string { + return "bar"; +} +// #endregion Type parameters (generics) + + + +// #region Parameters +export function FunctionWithOneParameter(parameter: string) { } + +export function FunctionWithNoParameters() { } + +export function FunctionWithMultipleParameters(parameter1: string, parameter2: number) { } +// #endregion Parameters + +export function Foo(): string { + return "foo"; +} + +/** + * Some general comment about Bar function. + * + * @beta Some comment on beta. + * @deprecated + */ +export function Bar(parameter1: string, parameter2: number): string { + return "bar"; +} + +// #region Return types +export function FunctionWithoutReturnType>(parameter1: string, parameter2: Promise) { + return "bar"; +} + +export function FunctionWithGenericReturnType(): Array { + return []; +} + +export function FunctionWithPrimitiveReturnType(): boolean { + return true; +} + +export function FunctionWithUnionReturnType(): "something" | "nothing" { + return "nothing"; +} + +export function FunctionWithIntersectionReturnType(): Earth & World { + return {}; +} +// #endregion Return types + +// ------------------------------------------------------ // export * from "./exported-functions"; // export { Kintamasis as Pakeistas } from "./exported-const-variables"; From 1134478de16cddab27402d70953bfc8dc983ec1b Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Fri, 8 Dec 2017 19:57:12 +0200 Subject: [PATCH 07/26] Function parameters table added. --- .../simple/docs/api/exported-functions.md | 4 -- .../examples/simple/docs/api/index.md | 71 ++++++++++++------- .../src/plugins/api-function-plugin.ts | 23 +++--- 3 files changed, 60 insertions(+), 38 deletions(-) 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 1c454f4a..156477bf 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 @@ -7,11 +7,9 @@ TODO: is deprecated or beta ### Type parameters -TODO ### Parameters -TODO ### Return type @@ -22,10 +20,8 @@ TODO: is deprecated or beta ### Type parameters -TODO ### Parameters -TODO ### Return type 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 f3df24f2..1b3b5d41 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index.md @@ -4,6 +4,24 @@ ## class: Earth +## function FunctionWithMultipleTypeParameters(parameter1: T, parameter2: P): string + +Bla bla + +TODO: is deprecated or beta + +### Type parameters + + +### Parameters + +| Name | Type | Description | +| ---------- | -------------------- | ----------- | +| parameter1 | [T][TypeParameter-0] | | +| parameter2 | [P][TypeParameter-1] | | + +### Return type + ## function FunctionWithTypeParameterDefault(parameter1: string, parameter2: T): string Some general comment about AnotherBar function. @@ -12,11 +30,13 @@ TODO: is deprecated or beta ### Type parameters -TODO ### Parameters -TODO +| Name | Type | Description | +| ---------- | -------------------- | ----------- | +| parameter1 | string | | +| parameter2 | [T][TypeParameter-2] | | ### Return type @@ -28,11 +48,13 @@ TODO: is deprecated or beta ### Type parameters -TODO ### Parameters -TODO +| Name | Type | Description | +| ---------- | -------------------- | ----------- | +| parameter1 | string | | +| parameter2 | [T][TypeParameter-3] | | ### Return type @@ -43,11 +65,13 @@ TODO: is deprecated or beta ### Type parameters -TODO ### Parameters -TODO +| Name | Type | Description | +| ---------- | ----------------------------- | ----------- | +| parameter1 | string | | +| parameter2 | Promise<[T][TypeParameter-4]> | | ### Return type @@ -58,11 +82,12 @@ TODO: is deprecated or beta ### Type parameters -TODO ### Parameters -TODO +| Name | Type | Description | +| --------- | ------ | ----------- | +| parameter | string | | ### Return type @@ -73,11 +98,9 @@ TODO: is deprecated or beta ### Type parameters -TODO ### Parameters -TODO ### Return type @@ -88,11 +111,13 @@ TODO: is deprecated or beta ### Type parameters -TODO ### Parameters -TODO +| Name | Type | Description | +| ---------- | ------ | ----------- | +| parameter1 | string | | +| parameter2 | number | | ### Return type @@ -103,11 +128,9 @@ TODO: is deprecated or beta ### Type parameters -TODO ### Parameters -TODO ### Return type @@ -119,11 +142,13 @@ TODO: is deprecated or beta ### Type parameters -TODO ### Parameters -TODO +| Name | Type | Description | +| ---------- | ------ | ----------- | +| parameter1 | string | | +| parameter2 | number | | ### Return type @@ -134,11 +159,13 @@ TODO: is deprecated or beta ### Type parameters -TODO ### Parameters -TODO +| Name | Type | Description | +| ---------- | ----------------------------- | ----------- | +| parameter1 | string | | +| parameter2 | Promise<[T][TypeParameter-5]> | | ### Return type @@ -149,11 +176,9 @@ TODO: is deprecated or beta ### Type parameters -TODO ### Parameters -TODO ### Return type @@ -164,11 +189,9 @@ TODO: is deprecated or beta ### Type parameters -TODO ### Parameters -TODO ### Return type @@ -179,11 +202,9 @@ TODO: is deprecated or beta ### Type parameters -TODO ### Parameters -TODO ### Return type @@ -194,11 +215,9 @@ TODO: is deprecated or beta ### Type parameters -TODO ### Parameters -TODO ### Return type 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 4a7a636d..0862ebf6 100644 --- a/packages/ts-docs-gen/src/plugins/api-function-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-function-plugin.ts @@ -55,16 +55,25 @@ export class ApiFunctionPlugin extends ApiItemPluginBase commentItem.text); } - // private resolveFunctionParameters(): string[] { - // const builder = new MarkdownBuilder(); - // return builder.GetOutput(); - // } + private resolveFunctionParameters(parameters: Contracts.ApiParameterDto[]): string[] { + if (parameters.length === 0) { + return []; + } + + const builder = new MarkdownBuilder(); + const header = ["Name", "Type", "Description"]; + const content = parameters.map(parameter => [parameter.Name, GeneratorHelpers.TypeDtoToMarkdownString(parameter.Type).Text]); + + return builder + .Table(header, content) + .GetOutput(); + } private resolveFunctionTypeParameters(typeParameters: Contracts.ApiTypeParameterDto[]): string[] { const builder = new MarkdownBuilder(); // typeParameters.map(parameter => { - // console.log(parameter); + // return []; // }); return builder.GetOutput(); @@ -77,8 +86,6 @@ export class ApiFunctionPlugin extends ApiItemPluginBase( data.ApiItem.TypeParameters, data.ExtractedData @@ -98,7 +105,7 @@ export class ApiFunctionPlugin extends ApiItemPluginBase Date: Fri, 8 Dec 2017 22:10:49 +0200 Subject: [PATCH 08/26] Api function plugin structure improved. --- .../src/plugins/api-function-plugin.ts | 164 +++++++++++------- 1 file changed, 98 insertions(+), 66 deletions(-) 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 0862ebf6..d8174ee9 100644 --- a/packages/ts-docs-gen/src/plugins/api-function-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-function-plugin.ts @@ -13,109 +13,141 @@ export class ApiFunctionPlugin extends ApiItemPluginBase 0) { - const typeParameters = typeParametersApiItems - .map(GeneratorHelpers.TypeParameterToString) - .join(", "); - - functionHeader += `<${typeParameters}>`; + // TODO: add description from @param jsdoc tag. + private resolveFunctionParameters(parameters: Contracts.ApiParameterDto[]): GeneratorHelpers.ReferenceDto { + if (parameters.length === 0) { + return { + References: [], + Text: [] + }; } - // Resolving parameters - const parametersString = parametersApiItems - .map(parameter => `${parameter.Name}: ${GeneratorHelpers.TypeDtoToString(parameter.Type)}`) - .join(", "); + let referenceIds: string[] = []; + const header = ["Name", "Type", "Description"]; - functionHeader += `(${parametersString})`; + const content = parameters.map(parameter => { + const parameterTypeDto = GeneratorHelpers.TypeDtoToMarkdownString(parameter.Type); - // Resolving return type - // Ask @Martynas for cases where function have no return type. - if (apiItem.ReturnType != null) { - functionHeader += ": " + GeneratorHelpers.TypeDtoToString(apiItem.ReturnType); - } + referenceIds = referenceIds.concat(parameterTypeDto.References); - return functionHeader; - } + return [parameter.Name, parameterTypeDto.Text]; + }); - private resolveDocumentationComment(metaData: Contracts.ApiMetadataDto): string[] { - if (metaData.DocumentationComment.length === 0) { - return []; - } + const text = new MarkdownBuilder() + .Header("Parameters", 3) + .EmptyLine() + .Table(header, content, ExtractorHelpers.DEFAULT_TABLE_OPTIONS) + .EmptyLine() + .GetOutput(); - // TODO: implement ExtractorHelpers.FixSentence when comments separation implemented in `ts-extractor`. - return metaData.DocumentationComment.map(commentItem => commentItem.text); + return { + Text: text, + References: referenceIds + }; } - private resolveFunctionParameters(parameters: Contracts.ApiParameterDto[]): string[] { - if (parameters.length === 0) { - return []; + // TODO: add description from @template jsdoc tag. + private resolveFunctionTypeParameters(typeParameters: Contracts.ApiTypeParameterDto[]): GeneratorHelpers.ReferenceDto { + let referenceIds: string[] = []; + + if (typeParameters.length === 0) { + return { + References: [], + Text: [] + }; } - const builder = new MarkdownBuilder(); - const header = ["Name", "Type", "Description"]; - const content = parameters.map(parameter => [parameter.Name, GeneratorHelpers.TypeDtoToMarkdownString(parameter.Type).Text]); + const header = ["Name", "Constraint type", "Default type"]; + const content = typeParameters.map(typeParameter => { + let constraintType: string = ""; + let defaultType: string = ""; + + if (typeParameter.ConstraintType) { + const parsedConstraintType = GeneratorHelpers.TypeDtoToMarkdownString(typeParameter.ConstraintType); + + referenceIds = referenceIds.concat(parsedConstraintType.References); + constraintType = parsedConstraintType.Text; + } + + if (typeParameter.DefaultType) { + const parsedDefaultType = GeneratorHelpers.TypeDtoToMarkdownString(typeParameter.DefaultType); - return builder - .Table(header, content) + referenceIds = referenceIds.concat(parsedDefaultType.References); + defaultType = parsedDefaultType.Text; + } + + return [typeParameter.Name, constraintType, defaultType]; + }); + + const text = new MarkdownBuilder() + .Header("Type parameters", 3) + .EmptyLine() + .Table(header, content, ExtractorHelpers.DEFAULT_TABLE_OPTIONS) + .EmptyLine() .GetOutput(); + + return { + References: referenceIds, + Text: text + }; } - private resolveFunctionTypeParameters(typeParameters: Contracts.ApiTypeParameterDto[]): string[] { - const builder = new MarkdownBuilder(); + private resolveReturnType(typeDto?: Contracts.TypeDto): GeneratorHelpers.ReferenceDto { + if (typeDto == null) { + return { + References: [], + Text: [] + }; + } - // typeParameters.map(parameter => { - // return []; - // }); + const parsedReturnType = GeneratorHelpers.TypeDtoToMarkdownString(typeDto); - return builder.GetOutput(); + const text = new MarkdownBuilder() + .Header("Return type", 3) + .EmptyLine() + .Text(parsedReturnType.Text) + .EmptyLine() + .GetOutput(); + + return { + Text: text, + References: parsedReturnType.References + }; } public Render(data: PluginData): RenderItemOutputDto { const [, alias] = data.Reference; + const parameters = ExtractorHelpers.GetApiItemsFromReferenceTuple( data.ApiItem.Parameters, data.ExtractedData ); + const resolvedParametersDto = this.resolveFunctionParameters(parameters); const typeParameters = ExtractorHelpers.GetApiItemsFromReferenceTuple( data.ApiItem.TypeParameters, data.ExtractedData ); + const resolvedTypeParametersDto = this.resolveFunctionTypeParameters(typeParameters); + + const resolvedReturnTypeDto = this.resolveReturnType(data.ApiItem.ReturnType); - const headerString = this.resolveFunctionHeader(alias, parameters, typeParameters, data.ApiItem); const builder = new MarkdownBuilder() - .Header(headerString, 2) - .EmptyLine() - .Text(this.resolveDocumentationComment(data.ApiItem.Metadata)) - .EmptyLine() - .Text("TODO: is deprecated or beta") - .EmptyLine() - .Header("Type parameters", 3) + .Header(ExtractorHelpers.ApiFunctionToString(alias, data.ApiItem, parameters), 2) .EmptyLine() - .Text(this.resolveFunctionTypeParameters(typeParameters)) - .EmptyLine() - .Header("Parameters", 3) - .EmptyLine() - .Text(this.resolveFunctionParameters(parameters)) - .EmptyLine() - .Header("Return type", 3); - - // const returnTypeDto = GeneratorHelpers.TypeDtoToMarkdownString(data.ApiItem.ReturnType!); - // console.log(returnTypeDto); + .Text(GeneratorHelpers.RenderApiItemMetadata(data.ApiItem)) + .Text(resolvedTypeParametersDto.Text) + .Text(resolvedParametersDto.Text) + .Text(resolvedReturnTypeDto.Text); return { Heading: alias, ApiItem: data.ApiItem, - References: [], + References: [ + ...resolvedParametersDto.References, + ...resolvedTypeParametersDto.References, + ...resolvedReturnTypeDto.References + ], RenderOutput: builder.GetOutput() }; } From 9f96185aeed932fe006d8b2ce82eaed8b5a63822 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Fri, 8 Dec 2017 22:11:07 +0200 Subject: [PATCH 09/26] Unnecessary function removed from GeneratorHelpers. --- packages/ts-docs-gen/src/generator-helpers.ts | 80 ++----------------- 1 file changed, 5 insertions(+), 75 deletions(-) diff --git a/packages/ts-docs-gen/src/generator-helpers.ts b/packages/ts-docs-gen/src/generator-helpers.ts index 0a36a923..a03c4555 100644 --- a/packages/ts-docs-gen/src/generator-helpers.ts +++ b/packages/ts-docs-gen/src/generator-helpers.ts @@ -2,11 +2,14 @@ import { Contracts } from "ts-extractor"; import { MarkdownGenerator, MarkdownBuilder } from "@simplrjs/markdown"; export namespace GeneratorHelpers { - export interface TypeToStringDto { + export type TypeToStringDto = ReferenceDto; + + export interface ReferenceDto { References: string[]; - Text: string; + Text: T; } + // TODO: implement type literal and function type. export function TypeDtoToMarkdownString(type: Contracts.TypeDto): TypeToStringDto { let references: string[] = []; let text: string = ""; @@ -61,79 +64,6 @@ export namespace GeneratorHelpers { }; } - export function TypeDtoToString(type: Contracts.TypeDto): string { - let text: string = ""; - - switch (type.ApiTypeKind) { - case Contracts.TypeKinds.Union: - case Contracts.TypeKinds.Intersection: { - const symbol = type.ApiTypeKind === Contracts.TypeKinds.Union ? "|" : "&"; - - if (type.ReferenceId != null) { - text = MarkdownGenerator.Link(type.Name || type.Text, type.ReferenceId, true); - break; - } - - type.Types - .map(TypeDtoToMarkdownString) - .forEach(typeItem => { - if (text === "") { - text = typeItem.Text; - } else { - text += ` ${symbol} ${typeItem.Text}`; - } - }); - break; - } - case Contracts.TypeKinds.Basic: - default: { - // Generics - if (type.Name != null && type.Generics != null) { - const generics = type.Generics.map(TypeDtoToMarkdownString); - text += `<${generics.map(x => x.Text).join(", ")}>`; - } - - // Basic type with reference. - if (type.ReferenceId != null) { - text = MarkdownGenerator.Link(type.Name || type.Text, type.ReferenceId, true); - } else { - text = type.Name || type.Text; - } - } - } - - return text; - } - - export function TypeParameterToString(typeParameter: Contracts.ApiTypeParameterDto): string { - let output = typeParameter.Name; - - if (typeParameter.ConstraintType != null) { - output += ` extends ${TypeDtoToString(typeParameter.ConstraintType)}`; - } - - if (typeParameter.DefaultType != null) { - output += ` = ${TypeDtoToString(typeParameter.DefaultType)}`; - } - - return output; - } - - // TODO: implement. - export function TypeParameterToMarkdownString(typeParameter: Contracts.ApiTypeParameterDto): string { - let output = typeParameter.Name; - - if (typeParameter.ConstraintType != null) { - output += ` extends ${TypeDtoToString(typeParameter.ConstraintType)}`; - } - - if (typeParameter.DefaultType != null) { - output += ` = ${TypeDtoToString(typeParameter.DefaultType)}`; - } - - return output; - } - export enum JSDocTags { Beta = "beta", Deprecated = "deprecated", From 54701d7e7be93d8ba4c29c99a4b2eb75c56aba45 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Fri, 8 Dec 2017 22:12:12 +0200 Subject: [PATCH 10/26] References malwared references skipping in output files added. --- packages/ts-docs-gen/src/file-manager.ts | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/packages/ts-docs-gen/src/file-manager.ts b/packages/ts-docs-gen/src/file-manager.ts index d0c55974..ca83d71a 100644 --- a/packages/ts-docs-gen/src/file-manager.ts +++ b/packages/ts-docs-gen/src/file-manager.ts @@ -59,11 +59,13 @@ export class FileManager extends FileManagerBaseBase { for (const item of items) { if (this.renderItemIsItemOutputDto(item)) { item.References - .forEach(referenceId => - references.push( - MarkdownGenerator.LinkDefinition(referenceId, this.referenceToFile.get(referenceId) || "#__error") - ) - ); + .forEach(referenceId => { + const referenceString = this.referenceToFile.get(referenceId); + + if (referenceString) { + references.push(MarkdownGenerator.LinkDefinition(referenceId, referenceString)); + } + }); } } From 90d74f092f7595514d2e79009f962c6eed9de46c Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Fri, 8 Dec 2017 22:12:40 +0200 Subject: [PATCH 11/26] ApiFunctionToString added to ExtractorHelpers. --- packages/ts-docs-gen/src/extractor-helpers.ts | 26 ++++++++++++++++--- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/packages/ts-docs-gen/src/extractor-helpers.ts b/packages/ts-docs-gen/src/extractor-helpers.ts index 7a8f1c9e..60a25124 100644 --- a/packages/ts-docs-gen/src/extractor-helpers.ts +++ b/packages/ts-docs-gen/src/extractor-helpers.ts @@ -1,7 +1,16 @@ import { Contracts, ExtractDto } from "ts-extractor"; import { ReferenceTuple } from "./contracts/reference-tuple"; +import { Contracts as MarkdownContracts } from "@simplrjs/markdown"; export namespace ExtractorHelpers { + export const DEFAULT_CODE_OPTIONS = { + lang: "typescript" + }; + + export const DEFAULT_TABLE_OPTIONS: MarkdownContracts.TableOptions = { + removeColumnIfEmpty: true + }; + export function GetReferenceTuples( extractedData: ExtractDto, entryFile: Contracts.ApiSourceFileDto, @@ -81,10 +90,6 @@ export namespace ExtractorHelpers { return result; } - export const DEFAULT_CODE_OPTIONS = { - lang: "typescript" - }; - export function FixSentence(sentence: string, punctuationMark: string = "."): string { const trimmedSentence = sentence.trim(); const punctuationMarks = ".!:;,-"; @@ -121,4 +126,17 @@ export namespace ExtractorHelpers { return `type ${name} = ${item.Type.Text};`; } + + export function ApiFunctionToString( + alias: string, + apiItem: Contracts.ApiFunctionDto, + parametersApiItems: Contracts.ApiParameterDto[] + ): string { + const name = alias || apiItem.Name; + const parametersString = parametersApiItems + .map(x => x.Name) + .join(", "); + + return `${name}(${parametersString})`; + } } From d6869443e605ecb88f81717debdc24dccdbe0b43 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Fri, 8 Dec 2017 22:13:17 +0200 Subject: [PATCH 12/26] Generated example code updated. --- .../simple/docs/api/exported-functions.md | 22 +- .../examples/simple/docs/api/index.md | 197 ++++++++---------- 2 files changed, 92 insertions(+), 127 deletions(-) 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 156477bf..bc4a45b3 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,27 +1,15 @@ # exported-functions -## function Foo(): string - - -TODO: is deprecated or beta - -### Type parameters - - -### Parameters - +## Foo() ### Return type -## function Bar(): string - - -TODO: is deprecated or beta +string -### Type parameters +## Bar() -### Parameters +### Return type +string -### Return type 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 4531c375..0e85f970 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index.md @@ -1,244 +1,221 @@ +[ClassDeclaration-1]: index.md#class-earth +[ClassDeclaration-0]: index.md#class-world [EnumDeclaration-0]: index.md#uogos # index ## class: World -<<<<<<< HEAD ## class: Earth -## function FunctionWithMultipleTypeParameters(parameter1: T, parameter2: P): string +## FunctionWithMultipleTypeParameters(parameter1, parameter2) Bla bla -TODO: is deprecated or beta - ### Type parameters +| Name | Constraint type | +| ---- | --------------- | +| T | Object | +| P | | ### Parameters -| Name | Type | Description | -| ---------- | -------------------- | ----------- | -| parameter1 | [T][TypeParameter-0] | | -| parameter2 | [P][TypeParameter-1] | | +| Name | Type | +| ---------- | -------------------- | +| parameter1 | [T][TypeParameter-0] | +| parameter2 | [P][TypeParameter-1] | ### Return type -## function FunctionWithTypeParameterDefault(parameter1: string, parameter2: T): string - -Some general comment about AnotherBar function. - -TODO: is deprecated or beta - -### Type parameters - +string -### Parameters - -| Name | Type | Description | -| ---------- | -------------------- | ----------- | -| parameter1 | string | | -| parameter2 | [T][TypeParameter-2] | | - -### Return type -## function FunctionWithTypeParameterConstraint(parameter1: string, parameter2: T): string +## FunctionWithTypeParameterDefault(parameter1, parameter2) Some general comment about AnotherBar function. -TODO: is deprecated or beta - ### Type parameters +| Name | Constraint type | Default type | +| ---- | --------------- | ------------ | +| T | Object | __type | ### Parameters -| Name | Type | Description | -| ---------- | -------------------- | ----------- | -| parameter1 | string | | -| parameter2 | [T][TypeParameter-3] | | +| Name | Type | +| ---------- | -------------------- | +| parameter1 | string | +| parameter2 | [T][TypeParameter-2] | ### Return type -## function AnotherFoo>(parameter1: string, parameter2: Promise): string +string + +## FunctionWithTypeParameterConstraint(parameter1, parameter2) -TODO: is deprecated or beta +Some general comment about AnotherBar function. ### Type parameters +| Name | Constraint type | +| ---- | --------------- | +| T | Object | ### Parameters -| Name | Type | Description | -| ---------- | ----------------------------- | ----------- | -| parameter1 | string | | -| parameter2 | Promise<[T][TypeParameter-4]> | | +| Name | Type | +| ---------- | -------------------- | +| parameter1 | string | +| parameter2 | [T][TypeParameter-3] | ### Return type -## function FunctionWithOneParameter(parameter: string): void +string -TODO: is deprecated or beta +## AnotherFoo(parameter1, parameter2) ### Type parameters +| Name | Constraint type | +| ---- | --------------- | +| T | Array | ### Parameters -| Name | Type | Description | -| --------- | ------ | ----------- | -| parameter | string | | +| Name | Type | +| ---------- | ------- | +| parameter1 | string | +| parameter2 | Promise | ### Return type -## function FunctionWithNoParameters(): void +string -TODO: is deprecated or beta - -### Type parameters - +## FunctionWithOneParameter(parameter) ### Parameters +| Name | Type | +| --------- | ------ | +| parameter | string | ### Return type -## function FunctionWithMultipleParameters(parameter1: string, parameter2: number): void +void -TODO: is deprecated or beta - -### Type parameters - - -### Parameters - -| Name | Type | Description | -| ---------- | ------ | ----------- | -| parameter1 | string | | -| parameter2 | number | | +## FunctionWithNoParameters() ### Return type -## function Foo(): string - +void -TODO: is deprecated or beta - -### Type parameters +## FunctionWithMultipleParameters(parameter1, parameter2) ### Parameters +| Name | Type | +| ---------- | ------ | +| parameter1 | string | +| parameter2 | number | ### Return type -## function Bar(parameter1: string, parameter2: number): string +void -Some general comment about Bar function. -TODO: is deprecated or beta - -### Type parameters - - -### Parameters - -| Name | Type | Description | -| ---------- | ------ | ----------- | -| parameter1 | string | | -| parameter2 | number | | +## Foo() ### Return type -## function FunctionWithoutReturnType>(parameter1: string, parameter2: Promise): string +string -TODO: is deprecated or beta +## Bar(parameter1, parameter2) -### Type parameters +Warning: Beta! + +Deprecated! +Some general comment about Bar function. ### Parameters -| Name | Type | Description | -| ---------- | ----------------------------- | ----------- | -| parameter1 | string | | -| parameter2 | Promise<[T][TypeParameter-5]> | | +| Name | Type | +| ---------- | ------ | +| parameter1 | string | +| parameter2 | number | ### Return type -## function FunctionWithGenericReturnType(): Array +string -TODO: is deprecated or beta +## FunctionWithoutReturnType(parameter1, parameter2) ### Type parameters +| Name | Constraint type | +| ---- | --------------- | +| T | Array | ### Parameters +| Name | Type | +| ---------- | ------- | +| parameter1 | string | +| parameter2 | Promise | ### Return type -## function FunctionWithPrimitiveReturnType(): true | false - - -TODO: is deprecated or beta - -### Type parameters - +string -### Parameters +## FunctionWithGenericReturnType() ### Return type -## function FunctionWithUnionReturnType(): "something" | "nothing" +Array -TODO: is deprecated or beta +## FunctionWithPrimitiveReturnType() -### Type parameters +### Return type +true | false -### Parameters +## FunctionWithUnionReturnType() ### Return type -## function FunctionWithIntersectionReturnType(): Earth & World +"something" | "nothing" -TODO: is deprecated or beta +## FunctionWithIntersectionReturnType() -### Type parameters - - -### Parameters +### Return type +[Earth][ClassDeclaration-1] & [World][ClassDeclaration-0] -### Return type -======= ->>>>>>> origin/dev ## 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 -<<<<<<< HEAD -======= > Some summary about this package version. ->>>>>>> origin/dev ```typescript From 23e4cd8d93d259e18bacf3e8fae3ed25be7c3a9f Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Tue, 19 Dec 2017 19:01:30 +0200 Subject: [PATCH 13/26] Conflicts resolved. --- packages/ts-docs-gen/src/extractor-helpers.ts | 142 ------------------ packages/ts-docs-gen/src/file-manager.ts | 4 + packages/ts-docs-gen/src/generator-helpers.ts | 37 ++++- .../src/plugins/api-enum-plugin.ts | 24 +-- .../src/plugins/api-function-plugin.ts | 46 +++--- .../cases/__tests__/simple-project-1.test.ts | 19 +++ .../cases/__tests__/simple-project-2.test.ts | 19 +++ 7 files changed, 110 insertions(+), 181 deletions(-) delete mode 100644 packages/ts-docs-gen/src/extractor-helpers.ts create mode 100644 packages/ts-docs-gen/tests/cases/__tests__/simple-project-1.test.ts create mode 100644 packages/ts-docs-gen/tests/cases/__tests__/simple-project-2.test.ts diff --git a/packages/ts-docs-gen/src/extractor-helpers.ts b/packages/ts-docs-gen/src/extractor-helpers.ts deleted file mode 100644 index 60a25124..00000000 --- a/packages/ts-docs-gen/src/extractor-helpers.ts +++ /dev/null @@ -1,142 +0,0 @@ -import { Contracts, ExtractDto } from "ts-extractor"; -import { ReferenceTuple } from "./contracts/reference-tuple"; -import { Contracts as MarkdownContracts } from "@simplrjs/markdown"; - -export namespace ExtractorHelpers { - export const DEFAULT_CODE_OPTIONS = { - lang: "typescript" - }; - - export const DEFAULT_TABLE_OPTIONS: MarkdownContracts.TableOptions = { - removeColumnIfEmpty: true - }; - - export function GetReferenceTuples( - extractedData: ExtractDto, - entryFile: Contracts.ApiSourceFileDto, - itemsReference: Contracts.ApiItemReferenceTuple - ): ReferenceTuple[] { - let list: ReferenceTuple[] = []; - - for (const [alias, references] of itemsReference) { - for (const referenceId of references) { - // Check if item is ExportSpecifier or ExportDeclaration. - const apiItem = extractedData.Registry[referenceId]; - - switch (apiItem.ApiKind) { - case Contracts.ApiItemKinds.Export: { - const referenceTuples = GetReferenceTuples(extractedData, entryFile, apiItem.Members); - list = list.concat(referenceTuples); - break; - } - case Contracts.ApiItemKinds.ExportSpecifier: { - if (apiItem.ApiItems == null) { - console.warn(`ApiItems are missing in "${apiItem.Name}"?`); - break; - } - const referenceTuples = GetReferenceTuples(extractedData, entryFile, [[apiItem.Name, apiItem.ApiItems]]); - list = list.concat(referenceTuples); - break; - } - default: { - list.push([referenceId, alias]); - } - } - } - } - - return list; - } - - export function ApiVariableToString(item: Contracts.ApiVariableDto, alias?: string): string { - const name = alias != null ? alias : item.Name; - - return `${item.VariableDeclarationType} ${name}: ${item.Type.Text};`; - } - - export function ReconstructEnumCode(alias: string, memberItems: Contracts.ApiEnumMemberDto[]): string[] { - // Constructing enum body. - const membersStrings = memberItems.map((memberItem, index, array) => { - // Add an enum name - let memberString = `${ExtractorHelpers.Tab()} ${memberItem.Name}`; - - // Add an enum member value if it exists. - if (memberItem.Value) { - memberString += ` = ${memberItem.Value}`; - } - - // Add a comma if current item is not the last item - if (index !== memberItems.length - 1) { - memberString += ","; - } - - return memberString; - }); - - // Construct enum code output - return [ - `enum ${alias} {`, - ...membersStrings, - "}" - ]; - } - - const TAB_STRING = " "; - export function Tab(size: number = 1): string { - let result: string = ""; - for (let i = 0; i < size; i++) { - result += TAB_STRING; - } - return result; - } - - export function FixSentence(sentence: string, punctuationMark: string = "."): string { - const trimmedSentence = sentence.trim(); - const punctuationMarks = ".!:;,-"; - - const lastSymbol = trimmedSentence[trimmedSentence.length - 1]; - - if (punctuationMarks.indexOf(lastSymbol) !== -1) { - return trimmedSentence; - } - - return trimmedSentence + punctuationMark; - } - - export function GetApiItemsFromReferenceTuple( - items: Contracts.ApiItemReferenceTuple, - extractedData: ExtractDto - ): T[] { - const apiItems: T[] = []; - - for (const itemReferences of items) { - const [, references] = itemReferences; - - for (const reference of references) { - const apiItem = extractedData.Registry[reference] as T; - apiItems.push(apiItem); - } - } - - return apiItems; - } - - export function ApiTypeToString(item: Contracts.ApiTypeDto, alias?: string): string { - const name = alias != null ? alias : item.Name; - - return `type ${name} = ${item.Type.Text};`; - } - - export function ApiFunctionToString( - alias: string, - apiItem: Contracts.ApiFunctionDto, - parametersApiItems: Contracts.ApiParameterDto[] - ): string { - const name = alias || apiItem.Name; - const parametersString = parametersApiItems - .map(x => x.Name) - .join(", "); - - return `${name}(${parametersString})`; - } -} diff --git a/packages/ts-docs-gen/src/file-manager.ts b/packages/ts-docs-gen/src/file-manager.ts index f268a4d4..d518b13a 100644 --- a/packages/ts-docs-gen/src/file-manager.ts +++ b/packages/ts-docs-gen/src/file-manager.ts @@ -67,6 +67,10 @@ export class FileManager implements FileManagerInterface { linkDefinitions.push( MarkdownGenerator.LinkDefinition(referenceId, resolvePath) ); + } else { + linkDefinitions.push( + MarkdownGenerator.LinkDefinition(referenceId, "Error") + ); } }); } diff --git a/packages/ts-docs-gen/src/generator-helpers.ts b/packages/ts-docs-gen/src/generator-helpers.ts index d8156135..6e70c329 100644 --- a/packages/ts-docs-gen/src/generator-helpers.ts +++ b/packages/ts-docs-gen/src/generator-helpers.ts @@ -1,5 +1,5 @@ import { Contracts, ExtractDto } from "ts-extractor"; -import { MarkdownGenerator, MarkdownBuilder } from "@simplrjs/markdown"; +import { MarkdownGenerator, MarkdownBuilder, Contracts as MarkdownContracts } from "@simplrjs/markdown"; import { ApiItemReference } from "./contracts/api-item-reference"; import { ApiItemKindsAdditional } from "./contracts/plugin"; @@ -207,6 +207,10 @@ export namespace GeneratorHelpers { lang: "typescript" }; + export const DEFAULT_TABLE_OPTIONS: MarkdownContracts.TableOptions = { + removeColumnIfEmpty: true + }; + export function FixSentence(sentence: string, punctuationMark: string = "."): string { const trimmedSentence = sentence.trim(); const punctuationMarks = ".!:;,-"; @@ -225,4 +229,35 @@ export namespace GeneratorHelpers { return `type ${name} = ${item.Type.Text};`; } + + export function ApiFunctionToString( + alias: string, + apiItem: Contracts.ApiFunctionDto, + parametersApiItems: Contracts.ApiParameterDto[] + ): string { + const name = alias || apiItem.Name; + const parametersString = parametersApiItems + .map(x => x.Name) + .join(", "); + + return `${name}(${parametersString})`; + } + + export function GetApiItemsFromReferenceTuple( + items: Contracts.ApiItemReferenceTuple, + extractedData: ExtractDto + ): T[] { + const apiItems: T[] = []; + + for (const itemReferences of items) { + const [, references] = itemReferences; + + for (const reference of references) { + const apiItem = extractedData.Registry[reference] as T; + apiItems.push(apiItem); + } + } + + return apiItems; + } } 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 76169dfb..481d6234 100644 --- a/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts @@ -1,4 +1,4 @@ -import { Contracts, ExtractDto } from "ts-extractor"; +import { Contracts } from "ts-extractor"; import { MarkdownGenerator, MarkdownBuilder } from "@simplrjs/markdown"; import { GeneratorHelpers } from "../generator-helpers"; @@ -23,23 +23,6 @@ export class ApiEnumPlugin implements Plugin { return MarkdownGenerator.Table(header, content, { removeColumnIfEmpty: true }); } - /** - * Resolve api items of an enum from ApiItemReferenceTuple. - */ - private getEnumMembers(members: Contracts.ApiItemReferenceTuple, extractedData: ExtractDto): Contracts.ApiEnumMemberDto[] { - const apiItems: Contracts.ApiEnumMemberDto[] = []; - - for (const memberReferences of members) { - const [, references] = memberReferences; - for (const reference of references) { - const apiItem = extractedData.Registry[reference] as Contracts.ApiEnumMemberDto; - apiItems.push(apiItem); - } - } - - return apiItems; - } - public Render(data: PluginOptions): PluginResult { const heading: string = data.Reference.Alias; const headings: PluginHeading[] = [ @@ -49,7 +32,10 @@ export class ApiEnumPlugin implements Plugin { } ]; - const enumMembers = this.getEnumMembers(data.ApiItem.Members, data.ExtractedData); + const enumMembers = GeneratorHelpers.GetApiItemsFromReferenceTuple( + data.ApiItem.Members, + data.ExtractedData + ); const builder = new MarkdownBuilder() .Header(heading, 2) .EmptyLine() 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 d8174ee9..93eb7caf 100644 --- a/packages/ts-docs-gen/src/plugins/api-function-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-function-plugin.ts @@ -1,16 +1,17 @@ import { Contracts } from "ts-extractor"; import { MarkdownBuilder } from "@simplrjs/markdown"; -import { ApiItemPluginBase } from "../abstractions/api-item-plugin-base"; -import { SupportedApiItemKindType } from "../contracts/supported-api-item-kind-type"; -import { RenderItemOutputDto } from "../contracts/render-item-output-dto"; -import { PluginData } from "../contracts/plugin-data"; import { GeneratorHelpers } from "../generator-helpers"; -import { ExtractorHelpers } from "../extractor-helpers"; +import { SupportedApiItemKindType, Plugin, PluginResult, PluginOptions, PluginHeading } from "../contracts/plugin"; +import { ApiFunctionDto } from "ts-extractor/dist/contracts"; -export class ApiFunctionPlugin extends ApiItemPluginBase { - public SupportedApiItemsKinds(): SupportedApiItemKindType[] { - return [this.SupportKind.Function]; +export class ApiFunctionPlugin implements Plugin { + public SupportedApiItemKinds(): SupportedApiItemKindType[] { + return [GeneratorHelpers.ApiItemKinds.Function]; + } + + public CheckApiItem(item: ApiFunctionDto): boolean { + return true; } // TODO: add description from @param jsdoc tag. @@ -36,7 +37,7 @@ export class ApiFunctionPlugin extends ApiItemPluginBase): RenderItemOutputDto { - const [, alias] = data.Reference; + public Render(data: PluginOptions): PluginResult { + const alias = data.Reference.Alias; - const parameters = ExtractorHelpers.GetApiItemsFromReferenceTuple( + const headings: PluginHeading[] = [ + { + ApiItemId: data.Reference.Id, + Heading: alias + } + ]; + + const parameters = GeneratorHelpers.GetApiItemsFromReferenceTuple( data.ApiItem.Parameters, data.ExtractedData ); const resolvedParametersDto = this.resolveFunctionParameters(parameters); - const typeParameters = ExtractorHelpers.GetApiItemsFromReferenceTuple( + const typeParameters = GeneratorHelpers.GetApiItemsFromReferenceTuple( data.ApiItem.TypeParameters, data.ExtractedData ); @@ -133,7 +141,7 @@ export class ApiFunctionPlugin extends ApiItemPluginBase { + const projectDirectory = "D:/Projects/ts-docs-gen/packages/ts-docs-gen/tests/cases/simple-project-1"; + const entryFiles = ["./index.ts"]; + + try { + const configuration = await new GeneratorConfigurationBuilder(projectDirectory) + .Build(entryFiles); + + const generator = new Generator(configuration); + + expect(generator.OutputData).toMatchSnapshot(); + done(); + } catch (error) { + done.fail(error); + } +}); diff --git a/packages/ts-docs-gen/tests/cases/__tests__/simple-project-2.test.ts b/packages/ts-docs-gen/tests/cases/__tests__/simple-project-2.test.ts new file mode 100644 index 00000000..a90eb911 --- /dev/null +++ b/packages/ts-docs-gen/tests/cases/__tests__/simple-project-2.test.ts @@ -0,0 +1,19 @@ +import { Generator } from "@src/generator"; +import { GeneratorConfigurationBuilder } from "@src/builders/generator-configuration-builder"; + +test("index", async done => { + const projectDirectory = "D:/Projects/ts-docs-gen/packages/ts-docs-gen/tests/cases/simple-project-2"; + const entryFiles = ["./index.ts","./foo.ts"]; + + try { + const configuration = await new GeneratorConfigurationBuilder(projectDirectory) + .Build(entryFiles); + + const generator = new Generator(configuration); + + expect(generator.OutputData).toMatchSnapshot(); + done(); + } catch (error) { + done.fail(error); + } +}); From 7e48d96b7f934b8fdf721ff50f528c15c4de440a Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Tue, 19 Dec 2017 20:07:51 +0200 Subject: [PATCH 14/26] Warning added for not found reference. --- packages/ts-docs-gen/src/file-manager.ts | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/packages/ts-docs-gen/src/file-manager.ts b/packages/ts-docs-gen/src/file-manager.ts index d518b13a..fce83990 100644 --- a/packages/ts-docs-gen/src/file-manager.ts +++ b/packages/ts-docs-gen/src/file-manager.ts @@ -61,16 +61,14 @@ export class FileManager implements FileManagerInterface { const filePath = path.dirname(fileLocation); const referenceString = this.referenceToFile.get(referenceId); + const resolvePath = path.relative(filePath, referenceString || "#__error"); - if (referenceString) { - const resolvePath = path.relative(filePath, referenceString); - linkDefinitions.push( - MarkdownGenerator.LinkDefinition(referenceId, resolvePath) - ); - } else { - linkDefinitions.push( - MarkdownGenerator.LinkDefinition(referenceId, "Error") - ); + linkDefinitions.push( + MarkdownGenerator.LinkDefinition(referenceId, resolvePath) + ); + + if (!referenceString) { + console.warn(`Reference "${referenceId}" not found. Check ${fileLocation}.`); } }); } From 751bdafd477918ac1722b6475339044f3ba0493f Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Tue, 19 Dec 2017 20:08:15 +0200 Subject: [PATCH 15/26] TypeDtoToMarkdownString generator helper improved. --- packages/ts-docs-gen/src/generator-helpers.ts | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/packages/ts-docs-gen/src/generator-helpers.ts b/packages/ts-docs-gen/src/generator-helpers.ts index 6e70c329..0c8e2d86 100644 --- a/packages/ts-docs-gen/src/generator-helpers.ts +++ b/packages/ts-docs-gen/src/generator-helpers.ts @@ -1,10 +1,10 @@ +import * as ts from "typescript"; import { Contracts, ExtractDto } from "ts-extractor"; import { MarkdownGenerator, MarkdownBuilder, Contracts as MarkdownContracts } from "@simplrjs/markdown"; import { ApiItemReference } from "./contracts/api-item-reference"; import { ApiItemKindsAdditional } from "./contracts/plugin"; export namespace GeneratorHelpers { - export type TypeToStringDto = ReferenceDto; export interface ReferenceDto { @@ -21,6 +21,11 @@ export namespace GeneratorHelpers { return Object.assign(Contracts.ApiItemKinds, ApiItemKindsAdditional); } + // TODO: reexport InternalSymbolName in ts-extractor. + export function IsTypeScriptInternalSymbolName(name: string): boolean { + return Object.values(ts.InternalSymbolName).indexOf(name) !== -1; + } + // TODO: implement type literal and function type. export function TypeDtoToMarkdownString(type: Contracts.TypeDto): TypeToStringDto { let references: string[] = []; @@ -61,11 +66,16 @@ export namespace GeneratorHelpers { } // Basic type with reference. - if (type.ReferenceId != null) { + // FIXME: do not use flag string. Exclude Type parameters references. + if (type.ReferenceId != null && type.FlagsString !== "TypeParameter") { text = MarkdownGenerator.Link(type.Name || type.Text, type.ReferenceId, true); references.push(type.ReferenceId); } else { - text = type.Name || type.Text; + if(type.Name == null || IsTypeScriptInternalSymbolName(type.Name)) { + text = type.Text; + } else { + text = type.Name; + } } } } From 84912fc6ee95e2e548f41d2da83f62e0fa45e289 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Tue, 19 Dec 2017 20:19:38 +0200 Subject: [PATCH 16/26] Markdown regenerated. --- .../simple/docs/api/exported-functions.md | 6 ----- .../examples/simple/docs/api/index.md | 26 +++++++++---------- 2 files changed, 13 insertions(+), 19 deletions(-) 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 dbf0a251..cd27b5a1 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,6 +1,3 @@ -<<<<<<< HEAD -# exported-functions - ## Foo() ### Return type @@ -13,7 +10,4 @@ string ### Return type string -======= -## function: Foo ->>>>>>> origin/dev 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 0ca9da9c..35e2551b 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index.md @@ -19,10 +19,10 @@ Bla bla ### Parameters -| Name | Type | -| ---------- | -------------------- | -| parameter1 | [T][TypeParameter-0] | -| parameter2 | [P][TypeParameter-1] | +| Name | Type | +| ---------- | ---- | +| parameter1 | T | +| parameter2 | P | ### Return type @@ -37,14 +37,14 @@ Some general comment about AnotherBar function. | Name | Constraint type | Default type | | ---- | --------------- | ------------ | -| T | Object | __type | +| T | Object | {} | ### Parameters -| Name | Type | -| ---------- | -------------------- | -| parameter1 | string | -| parameter2 | [T][TypeParameter-2] | +| Name | Type | +| ---------- | ------ | +| parameter1 | string | +| parameter2 | T | ### Return type @@ -63,10 +63,10 @@ Some general comment about AnotherBar function. ### Parameters -| Name | Type | -| ---------- | -------------------- | -| parameter1 | string | -| parameter2 | [T][TypeParameter-3] | +| Name | Type | +| ---------- | ------ | +| parameter1 | string | +| parameter2 | T | ### Return type From 509d1e8bc58a148ecc8ac01cffd265540e6cf88d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martynas=20=C5=BDilinskas?= Date: Thu, 21 Dec 2017 14:08:45 +0200 Subject: [PATCH 17/26] Fixed tslint. --- packages/ts-docs-gen/src/generator-helpers.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/ts-docs-gen/src/generator-helpers.ts b/packages/ts-docs-gen/src/generator-helpers.ts index 0c8e2d86..b2805eb6 100644 --- a/packages/ts-docs-gen/src/generator-helpers.ts +++ b/packages/ts-docs-gen/src/generator-helpers.ts @@ -71,7 +71,7 @@ export namespace GeneratorHelpers { text = MarkdownGenerator.Link(type.Name || type.Text, type.ReferenceId, true); references.push(type.ReferenceId); } else { - if(type.Name == null || IsTypeScriptInternalSymbolName(type.Name)) { + if (type.Name == null || IsTypeScriptInternalSymbolName(type.Name)) { text = type.Text; } else { text = type.Name; From e2c571ce21fe3df71aeec77c3bc390d6160f3fa5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martynas=20=C5=BDilinskas?= Date: Thu, 21 Dec 2017 14:08:58 +0200 Subject: [PATCH 18/26] Updated snapshots and updated gitignore. --- .gitignore | 4 ++-- .../simple-project-1.test.ts.snap | 13 ++++++------- .../simple-project-2.test.ts.snap | 10 +++------- .../cases/__tests__/simple-project-1.test.ts | 19 ------------------- .../cases/__tests__/simple-project-2.test.ts | 19 ------------------- 5 files changed, 11 insertions(+), 54 deletions(-) delete mode 100644 packages/ts-docs-gen/tests/cases/__tests__/simple-project-1.test.ts delete mode 100644 packages/ts-docs-gen/tests/cases/__tests__/simple-project-2.test.ts diff --git a/.gitignore b/.gitignore index 4f108f96..ccdfc1e3 100644 --- a/.gitignore +++ b/.gitignore @@ -292,5 +292,5 @@ coverage package-deps.json # Tests -*/__tests__/* -!*/__tests__/**/__snapshots__ +**/tests/cases/__tests__/*.test.ts + 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 9113bab0..78dd9a8e 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 @@ -1,12 +1,10 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP -exports[`index 1`] = ` +exports[`simple-project-1 1`] = ` Array [ Object { "FileLocation": "index.md", - "Output": Array [ - "# index", - "", + "Result": Array [ "## EnumList", "", "Simple list.", @@ -28,7 +26,7 @@ Array [ "", "## EnumListWithNumberValues", "", - "List with number values with no punctuation at the end of description.", + "List with number values with no punctuation at the end of description", "", "", "\`\`\`typescript", @@ -47,9 +45,10 @@ Array [ "", "## EnumListWithStringValues", "", + "Warning: Beta!", + "", + "Deprecated!", "", - "beta", - "deprecated", "", "\`\`\`typescript", "enum EnumListWithStringValues {", 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 4939fde2..5ef537ea 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 @@ -1,12 +1,10 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP -exports[`index 1`] = ` +exports[`simple-project-2 1`] = ` Array [ Object { "FileLocation": "index.md", - "Output": Array [ - "# index", - "", + "Result": Array [ "## class: Foo", "", "## class: FooStart", @@ -15,9 +13,7 @@ Array [ }, Object { "FileLocation": "foo.md", - "Output": Array [ - "# foo", - "", + "Result": Array [ "## class: Foo", "", ], diff --git a/packages/ts-docs-gen/tests/cases/__tests__/simple-project-1.test.ts b/packages/ts-docs-gen/tests/cases/__tests__/simple-project-1.test.ts deleted file mode 100644 index 85ee98a3..00000000 --- a/packages/ts-docs-gen/tests/cases/__tests__/simple-project-1.test.ts +++ /dev/null @@ -1,19 +0,0 @@ -import { Generator } from "@src/generator"; -import { GeneratorConfigurationBuilder } from "@src/builders/generator-configuration-builder"; - -test("index", async done => { - const projectDirectory = "D:/Projects/ts-docs-gen/packages/ts-docs-gen/tests/cases/simple-project-1"; - const entryFiles = ["./index.ts"]; - - try { - const configuration = await new GeneratorConfigurationBuilder(projectDirectory) - .Build(entryFiles); - - const generator = new Generator(configuration); - - expect(generator.OutputData).toMatchSnapshot(); - done(); - } catch (error) { - done.fail(error); - } -}); diff --git a/packages/ts-docs-gen/tests/cases/__tests__/simple-project-2.test.ts b/packages/ts-docs-gen/tests/cases/__tests__/simple-project-2.test.ts deleted file mode 100644 index a90eb911..00000000 --- a/packages/ts-docs-gen/tests/cases/__tests__/simple-project-2.test.ts +++ /dev/null @@ -1,19 +0,0 @@ -import { Generator } from "@src/generator"; -import { GeneratorConfigurationBuilder } from "@src/builders/generator-configuration-builder"; - -test("index", async done => { - const projectDirectory = "D:/Projects/ts-docs-gen/packages/ts-docs-gen/tests/cases/simple-project-2"; - const entryFiles = ["./index.ts","./foo.ts"]; - - try { - const configuration = await new GeneratorConfigurationBuilder(projectDirectory) - .Build(entryFiles); - - const generator = new Generator(configuration); - - expect(generator.OutputData).toMatchSnapshot(); - done(); - } catch (error) { - done.fail(error); - } -}); From abe47efc258a5d167fd9a574b07c99af1ab5c679 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martynas=20=C5=BDilinskas?= Date: Thu, 21 Dec 2017 15:50:00 +0200 Subject: [PATCH 19/26] Build code block for Function head. --- .../simple/docs/api/exported-functions.md | 8 +++ .../examples/simple/docs/api/index.md | 56 +++++++++++++++++++ packages/ts-docs-gen/src/generator-helpers.ts | 45 +++++++++++++++ .../src/plugins/api-function-plugin.ts | 9 ++- 4 files changed, 117 insertions(+), 1 deletion(-) 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 cd27b5a1..848a1922 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,5 +1,9 @@ ## Foo() +```typescript +function Foo(): string +``` + ### Return type string @@ -7,6 +11,10 @@ string ## Bar() +```typescript +function Bar(): string +``` + ### 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 35e2551b..5fb226d5 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index.md @@ -10,6 +10,10 @@ Bla bla +```typescript +function FunctionWithMultipleTypeParameters(parameter1: T, parameter2: P): string +``` + ### Type parameters | Name | Constraint type | @@ -33,6 +37,10 @@ string Some general comment about AnotherBar function. +```typescript +function FunctionWithTypeParameterDefault(parameter1: string, parameter2: T): string +``` + ### Type parameters | Name | Constraint type | Default type | @@ -55,6 +63,10 @@ string Some general comment about AnotherBar function. +```typescript +function FunctionWithTypeParameterConstraint(parameter1: string, parameter2: T): string +``` + ### Type parameters | Name | Constraint type | @@ -75,6 +87,10 @@ string ## AnotherFoo(parameter1, parameter2) +```typescript +function AnotherFoo(parameter1: string, parameter2: Promise): string +``` + ### Type parameters | Name | Constraint type | @@ -95,6 +111,10 @@ string ## FunctionWithOneParameter(parameter) +```typescript +function FunctionWithOneParameter(parameter: string): void +``` + ### Parameters | Name | Type | @@ -108,6 +128,10 @@ void ## FunctionWithNoParameters() +```typescript +function FunctionWithNoParameters(): void +``` + ### Return type void @@ -115,6 +139,10 @@ void ## FunctionWithMultipleParameters(parameter1, parameter2) +```typescript +function FunctionWithMultipleParameters(parameter1: string, parameter2: number): void +``` + ### Parameters | Name | Type | @@ -129,6 +157,10 @@ void ## Foo() +```typescript +function Foo(): string +``` + ### Return type string @@ -142,6 +174,10 @@ string Some general comment about Bar function. +```typescript +function Bar(parameter1: string, parameter2: number): string +``` + ### Parameters | Name | Type | @@ -156,6 +192,10 @@ string ## FunctionWithoutReturnType(parameter1, parameter2) +```typescript +function FunctionWithoutReturnType(parameter1: string, parameter2: Promise): string +``` + ### Type parameters | Name | Constraint type | @@ -176,6 +216,10 @@ string ## FunctionWithGenericReturnType() +```typescript +function FunctionWithGenericReturnType(): string[] +``` + ### Return type Array @@ -183,6 +227,10 @@ Array ## FunctionWithPrimitiveReturnType() +```typescript +function FunctionWithPrimitiveReturnType(): boolean +``` + ### Return type true | false @@ -190,6 +238,10 @@ true | false ## FunctionWithUnionReturnType() +```typescript +function FunctionWithUnionReturnType(): "something" | "nothing" +``` + ### Return type "something" | "nothing" @@ -197,6 +249,10 @@ true | false ## FunctionWithIntersectionReturnType() +```typescript +function FunctionWithIntersectionReturnType(): Earth & World +``` + ### Return type [Earth][ClassDeclaration-1] & [World][ClassDeclaration-0] diff --git a/packages/ts-docs-gen/src/generator-helpers.ts b/packages/ts-docs-gen/src/generator-helpers.ts index b2805eb6..9081ac74 100644 --- a/packages/ts-docs-gen/src/generator-helpers.ts +++ b/packages/ts-docs-gen/src/generator-helpers.ts @@ -240,7 +240,52 @@ export namespace GeneratorHelpers { return `type ${name} = ${item.Type.Text};`; } + /** + * From ApiFunction to build function head. + * + * Return example: `function foo(arg: TValue): void` + */ export function ApiFunctionToString( + apiItem: Contracts.ApiFunctionDto, + typeParameters?: Contracts.ApiTypeParameterDto[], + parameters?: Contracts.ApiParameterDto[], + alias?: string + ): string { + const name = alias || apiItem.Name; + + // TypeParameters + let typeParametersString: string; + if (typeParameters != null && typeParameters.length > 0) { + const params: string[] = typeParameters.map(TypeParameterToString); + typeParametersString = `<${params.join(", ")}>`; + } else { + typeParametersString = ""; + } + + // Parameters + let parametersString: string; + if (parameters != null && parameters.length > 0) { + parametersString = parameters + .map(x => `${x.Name}: ${x.Type.Text}`) + .join(", "); + } else { + parametersString = ""; + } + + // ReturnType + const returnType = apiItem.ReturnType != null ? `: ${apiItem.ReturnType.Text}` : ""; + + return `function ${name}${typeParametersString}(${parametersString})${returnType}`; + } + + export function TypeParameterToString(apiItem: Contracts.ApiTypeParameterDto): string { + const $extends = apiItem.ConstraintType != null ? ` extends ${apiItem.ConstraintType.Text}` : ""; + const defaultType = apiItem.DefaultType != null ? ` = ${apiItem.DefaultType.Text}` : ""; + + return `${apiItem.Name}${$extends}${defaultType}`; + } + + export function ApiFunctionToSimpleString( alias: string, apiItem: Contracts.ApiFunctionDto, parametersApiItems: Contracts.ApiParameterDto[] 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 93eb7caf..c2c6e5a7 100644 --- a/packages/ts-docs-gen/src/plugins/api-function-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-function-plugin.ts @@ -141,9 +141,16 @@ export class ApiFunctionPlugin implements Plugin { const resolvedReturnTypeDto = this.resolveReturnType(data.ApiItem.ReturnType); const builder = new MarkdownBuilder() - .Header(GeneratorHelpers.ApiFunctionToString(alias, data.ApiItem, parameters), 2) + .Header(GeneratorHelpers.ApiFunctionToSimpleString(alias, data.ApiItem, 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); From ff69de69f1851413598646ce600b8fcca6fe58e4 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Thu, 21 Dec 2017 15:59:21 +0200 Subject: [PATCH 20/26] TypeDtoToMarkdownString updated. --- packages/ts-docs-gen/src/generator-helpers.ts | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/ts-docs-gen/src/generator-helpers.ts b/packages/ts-docs-gen/src/generator-helpers.ts index 0c8e2d86..f1dfa7a6 100644 --- a/packages/ts-docs-gen/src/generator-helpers.ts +++ b/packages/ts-docs-gen/src/generator-helpers.ts @@ -66,13 +66,13 @@ export namespace GeneratorHelpers { } // Basic type with reference. - // FIXME: do not use flag string. Exclude Type parameters references. - if (type.ReferenceId != null && type.FlagsString !== "TypeParameter") { - text = MarkdownGenerator.Link(type.Name || type.Text, type.ReferenceId, true); - references.push(type.ReferenceId); + if (type.Name == null || IsTypeScriptInternalSymbolName(type.Name)) { + text = type.Text; } else { - if(type.Name == null || IsTypeScriptInternalSymbolName(type.Name)) { - text = type.Text; + // FIXME: do not use flag string. Exclude Type parameters references. + if (type.ReferenceId != null && type.FlagsString !== "TypeParameter" && type.FlagsString !== "TypeLiteral") { + text = MarkdownGenerator.Link(type.Name || type.Text, type.ReferenceId, true); + references.push(type.ReferenceId); } else { text = type.Name; } From 9b08447ebf29fc94a22e92efc1ca7b750e250362 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Thu, 21 Dec 2017 16:00:01 +0200 Subject: [PATCH 21/26] Type strings escaped in ApiFunctionPlugin. --- packages/ts-docs-gen/src/plugins/api-function-plugin.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 93eb7caf..79aae20e 100644 --- a/packages/ts-docs-gen/src/plugins/api-function-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-function-plugin.ts @@ -1,5 +1,5 @@ import { Contracts } from "ts-extractor"; -import { MarkdownBuilder } from "@simplrjs/markdown"; +import { MarkdownBuilder, MarkdownGenerator } from "@simplrjs/markdown"; import { GeneratorHelpers } from "../generator-helpers"; import { SupportedApiItemKindType, Plugin, PluginResult, PluginOptions, PluginHeading } from "../contracts/plugin"; @@ -31,7 +31,7 @@ export class ApiFunctionPlugin implements Plugin { referenceIds = referenceIds.concat(parameterTypeDto.References); - return [parameter.Name, parameterTypeDto.Text]; + return [parameter.Name, MarkdownGenerator.EscapeString(parameterTypeDto.Text)]; }); const text = new MarkdownBuilder() @@ -67,14 +67,14 @@ export class ApiFunctionPlugin implements Plugin { const parsedConstraintType = GeneratorHelpers.TypeDtoToMarkdownString(typeParameter.ConstraintType); referenceIds = referenceIds.concat(parsedConstraintType.References); - constraintType = parsedConstraintType.Text; + constraintType = MarkdownGenerator.EscapeString(parsedConstraintType.Text); } if (typeParameter.DefaultType) { const parsedDefaultType = GeneratorHelpers.TypeDtoToMarkdownString(typeParameter.DefaultType); referenceIds = referenceIds.concat(parsedDefaultType.References); - defaultType = parsedDefaultType.Text; + defaultType = MarkdownGenerator.EscapeString(parsedDefaultType.Text); } return [typeParameter.Name, constraintType, defaultType]; From ac3da06030506185fb76a013b8163aea19b21e2c Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Thu, 21 Dec 2017 16:01:52 +0200 Subject: [PATCH 22/26] @simplr/markdown updated. --- common/config/rush/npm-shrinkwrap.json | 86 ++++++++++++++------------ packages/ts-docs-gen/package.json | 2 +- 2 files changed, 47 insertions(+), 41 deletions(-) diff --git a/common/config/rush/npm-shrinkwrap.json b/common/config/rush/npm-shrinkwrap.json index 285b9fda..d71ee5cf 100644 --- a/common/config/rush/npm-shrinkwrap.json +++ b/common/config/rush/npm-shrinkwrap.json @@ -6,9 +6,9 @@ "dependencies": { "@rush-temp/test-generator-cli": { "version": "file:projects/test-generator-cli.tgz", - "integrity": "sha1-7hRxKrHs2nw/Tg3difiN7wlLcpI=", + "integrity": "sha1-poL86JfifvnYdj6kO8BwW/R5VEA=", "requires": { - "@types/fs-extra": "4.0.6", + "@types/fs-extra": "4.0.7", "@types/handlebars": "4.0.36", "@types/yargs": "10.0.0", "fast-glob": "1.0.1", @@ -23,12 +23,12 @@ }, "@rush-temp/ts-docs-gen": { "version": "file:projects/ts-docs-gen.tgz", - "integrity": "sha1-q5PE2Czi6RYJoEbNl8S7rSkODP4=", + "integrity": "sha1-EOjVkNyk5eR6fdm0niJiuEltOls=", "requires": { - "@simplrjs/markdown": "1.0.1", - "@types/fs-extra": "4.0.6", - "@types/jest": "21.1.8", - "@types/sinon": "4.1.1", + "@simplrjs/markdown": "1.0.2", + "@types/fs-extra": "4.0.7", + "@types/jest": "21.1.9", + "@types/sinon": "4.1.2", "fast-glob": "1.0.1", "fs-extra": "4.0.3", "jest": "21.2.1", @@ -42,20 +42,20 @@ } }, "@simplrjs/markdown": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/@simplrjs/markdown/-/markdown-1.0.1.tgz", - "integrity": "sha512-5cRr5I/CVRwo8bLJOmui8Jf9iwXgVcr81+9rO93IyLutm5GBrkSA8ZSwzovVuWlgA36sml9Dklrl1xP4GQEurA==", + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/@simplrjs/markdown/-/markdown-1.0.2.tgz", + "integrity": "sha512-iGfzFQwjvnGle/vKuGy8o9cDfLtj6AVSLybK0bNTG08T0FG2CZuRSG6PQBaCRwSV9Wqmxu+JjDryVyZNPdNTVQ==", "requires": { "@types/string": "0.0.29", "string": "3.3.3" } }, "@types/fs-extra": { - "version": "4.0.6", - "resolved": "https://registry.npmjs.org/@types/fs-extra/-/fs-extra-4.0.6.tgz", - "integrity": "sha512-SVQDcOe1t7qSRzJFjkMx4V/0hc3TcGX/f51Dxx3Q/rpeg7nvFiort6QJTpJATOZH/YqhzJ1xt0qjvotxOJiCkQ==", + "version": "4.0.7", + "resolved": "https://registry.npmjs.org/@types/fs-extra/-/fs-extra-4.0.7.tgz", + "integrity": "sha512-BN48b/2F3kL0Ual7tjcHjj0Fl+nuYKtHa0G/xT3Q43HuCpN7rQD5vIx6Aqnl9x10oBI5xMJh8Ly+FQpP205JlA==", "requires": { - "@types/node": "8.0.58" + "@types/node": "8.5.2" } }, "@types/handlebars": { @@ -64,19 +64,19 @@ "integrity": "sha512-LjNiTX7TY7wtuC6y3QwC93hKMuqYhgV9A1uXBKNvZtVC8ZvyWAjZkJ5BvT0K7RKqORRYRLMrqCxpw5RgS+MdrQ==" }, "@types/jest": { - "version": "21.1.8", - "resolved": "https://registry.npmjs.org/@types/jest/-/jest-21.1.8.tgz", - "integrity": "sha512-hQbL8aBM/g5S++sM1gb4yC73Dg+FK3uYE+Ioht1RPy629+LV/RmH6q+e+jbQEwKJdWAP/YE4s67CPO+ElkMivg==" + "version": "21.1.9", + "resolved": "https://registry.npmjs.org/@types/jest/-/jest-21.1.9.tgz", + "integrity": "sha512-81wGgp3KLAhcrDQBeGADeuH1SvOmgZty5XF/mdPBOSxjEgAT9rcLr4CQCk2cRRjZE8vzmx7S1SPL6D/Z8OOR6A==" }, "@types/node": { - "version": "8.0.58", - "resolved": "https://registry.npmjs.org/@types/node/-/node-8.0.58.tgz", - "integrity": "sha512-V746iUU7eHNdzQipoACuguDlVhC7IHK8CES1jSkuFt352wwA84BCWPXaGekBd7R5XdNK5ReHONDVKxlL9IreAw==" + "version": "8.5.2", + "resolved": "https://registry.npmjs.org/@types/node/-/node-8.5.2.tgz", + "integrity": "sha512-KA4GKOpgXnrqEH2eCVhiv2CsxgXGQJgV1X0vsGlh+WCnxbeAE1GT44ZsTU1IN5dEeV/gDupKa7gWo08V5IxWVQ==" }, "@types/sinon": { - "version": "4.1.1", - "resolved": "https://registry.npmjs.org/@types/sinon/-/sinon-4.1.1.tgz", - "integrity": "sha512-4TaA0fxqXNhx8ph+cylpN/hBrkxru0LviHlfZU6Yljl6ztUL7enUFnJ3XMYruSsyycnZgfGqOiw1kiynKlXLNw==" + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/@types/sinon/-/sinon-4.1.2.tgz", + "integrity": "sha512-fL6bJHYRzbw/7ofbKiJ65SOAasoe5mZhHNSYKxWsF3sGl/arhRwDPwXJqM1xofKNTQD14HNX9VruicM7pm++mQ==" }, "@types/string": { "version": "0.0.29", @@ -107,9 +107,9 @@ } }, "ajv": { - "version": "5.5.1", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-5.5.1.tgz", - "integrity": "sha1-s4u4h22ehr7plJVqBOch6IskjrI=", + "version": "5.5.2", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-5.5.2.tgz", + "integrity": "sha1-c7Xuyj+rZT49P5Qis0GtQiBdyWU=", "requires": { "co": "4.6.0", "fast-deep-equal": "1.0.0", @@ -299,6 +299,11 @@ "resolved": "https://registry.npmjs.org/assert-plus/-/assert-plus-1.0.0.tgz", "integrity": "sha1-8S4PPF13sLHN2RRpQuTpbB5N1SU=" }, + "assign-symbols": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/assign-symbols/-/assign-symbols-1.0.0.tgz", + "integrity": "sha1-WWZ/QfrdTyDMvCu5a41Pf3jsA2c=" + }, "astral-regex": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/astral-regex/-/astral-regex-1.0.0.tgz", @@ -1525,7 +1530,7 @@ "resolved": "https://registry.npmjs.org/har-validator/-/har-validator-5.0.3.tgz", "integrity": "sha1-ukAsJmGU8VlW7xXg/PJCmT9qff0=", "requires": { - "ajv": "5.5.1", + "ajv": "5.5.2", "har-schema": "2.0.0" } }, @@ -4024,14 +4029,15 @@ "resolved": "https://registry.npmjs.org/split-string/-/split-string-3.1.0.tgz", "integrity": "sha512-NzNVhJDYpwceVVii8/Hu6DKfD2G+NrQHlS/V/qgv763EYudVwEcMQNxd2lh+0VrUByXN/oJkl5grOhYWvQUYiw==", "requires": { - "extend-shallow": "3.0.1" + "extend-shallow": "3.0.2" }, "dependencies": { "extend-shallow": { - "version": "3.0.1", - "resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-3.0.1.tgz", - "integrity": "sha512-Fg1xXAv+qXKdwHiJFMcZSqsMcbPlkzsZtf8KkLJ2fqnP+lqg2RjEKgDcSfO9CO1+p4LZKgApDBUUUqKaaRhwZQ==", + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-3.0.2.tgz", + "integrity": "sha1-Jqcarwc7OfshJxcnRhMcJwQCjbg=", "requires": { + "assign-symbols": "1.0.0", "is-extendable": "1.0.1" } }, @@ -4411,7 +4417,7 @@ "resolved": "https://registry.npmjs.org/ts-extractor/-/ts-extractor-2.0.0.tgz", "integrity": "sha512-snSSnVkhc/jDo0ppJa8t3/aIbMcI3qg6HsB/iC0UdG+5KzAKHGQBuM5QwaFng6O7KKbk/Ljb8RgwN5uwd1DYHA==", "requires": { - "@types/fs-extra": "4.0.6", + "@types/fs-extra": "4.0.7", "fs-extra": "4.0.3", "read-package-json": "2.0.12", "simplr-logger": "1.0.1", @@ -4470,13 +4476,13 @@ "resolve": "1.5.0", "semver": "5.4.1", "tslib": "1.8.1", - "tsutils": "2.13.0" + "tsutils": "2.13.1" } }, "tsutils": { - "version": "2.13.0", - "resolved": "https://registry.npmjs.org/tsutils/-/tsutils-2.13.0.tgz", - "integrity": "sha512-FuWzNJbMsp3gcZMbI3b5DomhW4Ia41vMxjN63nKWI0t7f+I3UmHfRl0TrXJTwI2LUduDG+eR1Mksp3pvtlyCFQ==", + "version": "2.13.1", + "resolved": "https://registry.npmjs.org/tsutils/-/tsutils-2.13.1.tgz", + "integrity": "sha512-XMOEvc2TiYesVSOJMI7OYPnBMSgcvERuGW5Li/J+2A0TuH607BPQnOLQ82oSPZCssB8c9+QGi6qhTBa/f1xQRA==", "requires": { "tslib": "1.8.1" } @@ -4793,13 +4799,13 @@ "string-width": "2.1.1", "which-module": "2.0.0", "y18n": "3.2.1", - "yargs-parser": "8.0.0" + "yargs-parser": "8.1.0" } }, "yargs-parser": { - "version": "8.0.0", - "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-8.0.0.tgz", - "integrity": "sha1-IdR2Mw5agieaS4gTRb8GYQLiGcY=", + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-8.1.0.tgz", + "integrity": "sha512-yP+6QqN8BmrgW2ggLtTbdrOyBNSI7zBa4IykmiV5R1wl1JWNxQvWhMfMdmzIYtKU7oP3OOInY/tl2ov3BDjnJQ==", "requires": { "camelcase": "4.1.0" } diff --git a/packages/ts-docs-gen/package.json b/packages/ts-docs-gen/package.json index 0647a35c..59d62ac7 100644 --- a/packages/ts-docs-gen/package.json +++ b/packages/ts-docs-gen/package.json @@ -15,7 +15,7 @@ "engine": "node >= 7.5.0", "author": "simplrjs (https://github.com/simplrjs)", "dependencies": { - "@simplrjs/markdown": "^1.0.1", + "@simplrjs/markdown": "^1.0.2", "@types/fs-extra": "^4.0.5", "fast-glob": "^1.0.1", "fs-extra": "^4.0.3", From aa5ad574f11fbcdc5805da3ce43925db14387c92 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Thu, 21 Dec 2017 16:02:24 +0200 Subject: [PATCH 23/26] Sample functions moved from examples to tests. --- .../examples/simple/docs/api/index.md | 328 +----------------- packages/ts-docs-gen/examples/simple/index.ts | 248 ++++++------- .../tests/cases/simple-project-1/index.ts | 96 +++++ 3 files changed, 200 insertions(+), 472 deletions(-) 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 35e2551b..c110e38b 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index.md @@ -1,330 +1,12 @@ -[ClassDeclaration-1]: index.md#class-earth -[ClassDeclaration-0]: index.md#class-world -[EnumDeclaration-0]: index.md#uogos -[ModuleDeclaration-1]: index\boonamespace.md#boonamespace -## class: World - -## class: Earth - -## FunctionWithMultipleTypeParameters(parameter1, parameter2) - -Bla bla - -### Type parameters - -| Name | Constraint type | -| ---- | --------------- | -| T | Object | -| P | | - -### Parameters - -| Name | Type | -| ---------- | ---- | -| parameter1 | T | -| parameter2 | P | - -### Return type - -string - - -## FunctionWithTypeParameterDefault(parameter1, parameter2) - -Some general comment about AnotherBar function. +## MyFunction() ### Type parameters -| Name | Constraint type | Default type | -| ---- | --------------- | ------------ | -| T | Object | {} | - -### Parameters - -| Name | Type | -| ---------- | ------ | -| parameter1 | string | -| parameter2 | T | +| Name | Constraint type | Default type | +| ---- | ------------------------------------------------------------- | ------------------------- | +| T | \{ myProperty: string; myPropertyTwo?: number | undefined; \} | \{ myProperty: string; \} | ### Return type -string - - -## FunctionWithTypeParameterConstraint(parameter1, parameter2) - -Some general comment about AnotherBar function. - -### Type parameters - -| Name | Constraint type | -| ---- | --------------- | -| T | Object | - -### Parameters - -| Name | Type | -| ---------- | ------ | -| parameter1 | string | -| parameter2 | T | - -### Return type - -string - - -## AnotherFoo(parameter1, parameter2) - -### Type parameters - -| Name | Constraint type | -| ---- | --------------- | -| T | Array | - -### Parameters - -| Name | Type | -| ---------- | ------- | -| parameter1 | string | -| parameter2 | Promise | - -### Return type - -string - - -## FunctionWithOneParameter(parameter) - -### Parameters - -| Name | Type | -| --------- | ------ | -| parameter | string | - -### Return type - -void - - -## FunctionWithNoParameters() - -### Return type - -void - - -## FunctionWithMultipleParameters(parameter1, parameter2) - -### Parameters - -| Name | Type | -| ---------- | ------ | -| parameter1 | string | -| parameter2 | number | - -### Return type - -void - - -## Foo() - -### Return type - -string - - -## Bar(parameter1, parameter2) - -Warning: Beta! - -Deprecated! - -Some general comment about Bar function. - -### Parameters - -| Name | Type | -| ---------- | ------ | -| parameter1 | string | -| parameter2 | number | - -### Return type - -string - - -## FunctionWithoutReturnType(parameter1, parameter2) - -### Type parameters - -| Name | Constraint type | -| ---- | --------------- | -| T | Array | - -### Parameters - -| Name | Type | -| ---------- | ------- | -| parameter1 | string | -| parameter2 | Promise | - -### Return type - -string - - -## FunctionWithGenericReturnType() - -### Return type - -Array - - -## FunctionWithPrimitiveReturnType() - -### Return type - -true | false - - -## FunctionWithUnionReturnType() - -### Return type - -"something" | "nothing" - - -## FunctionWithIntersectionReturnType() - -### Return type - -[Earth][ClassDeclaration-1] & [World][ClassDeclaration-0] - - -## 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" -} -``` - -| Name | Value | -| ------- | --------- | -| Jokie | "jokie" | -| Braskes | "braskes" | - -## Skaiciai - - -```typescript -enum Skaiciai { - Nulis = 0, - Vienas = 1, - Du = 2 -} -``` - -| Name | Value | -| ------ | ----- | -| Nulis | 0 | -| Vienas | 1 | -| Du | 2 | - -## Sarasas - - -```typescript -enum Sarasas { - Pirmas = 0, - Antras = 1, - Trecias = 2 -} -``` - -| Name | Value | Description | -| ------- | ----- | --------------------- | -| Pirmas | 0 | Pirmo description'as | -| Antras | 1 | Antro description'as | -| Trecias | 2 | Trečio description'as | - -## ConstSkaiciai - - -```typescript -enum ConstSkaiciai { - PirmasC = 0, - AntrasC = 1, - TreciasC = 2 -} -``` - -| Name | Value | -| -------- | ----- | -| PirmasC | 0 | -| AntrasC | 1 | -| TreciasC | 2 | - -## ConstSarasas - - -```typescript -enum ConstSarasas { - PirmasC = 0, - AntrasC = 1, - TreciasC = 2 -} -``` - -| Name | Value | Description | -| -------- | ----- | --------------------- | -| PirmasC | 0 | Pirmo description'as | -| AntrasC | 1 | Antro description'as | -| TreciasC | 2 | Trečio description'as | - -## ConstUogos - - -```typescript -enum ConstUogos { - Jokie = "jokie", - Braskes = "braskes" -} -``` - -| Name | Value | -| ------- | --------- | -| Jokie | "jokie" | -| Braskes | "braskes" | - -## Hello - -Deprecated: Use uogos instead ;)! - -```typescript -type Hello = Uogos; -``` - -### Type - -[Uogos][EnumDeclaration-0] - -# FooNamespace - -## [BooNamespace][ModuleDeclaration-1] +T diff --git a/packages/ts-docs-gen/examples/simple/index.ts b/packages/ts-docs-gen/examples/simple/index.ts index b5171eb5..0e7421ba 100644 --- a/packages/ts-docs-gen/examples/simple/index.ts +++ b/packages/ts-docs-gen/examples/simple/index.ts @@ -2,8 +2,8 @@ // import { Foo } from "./exported-functions"; -export class World { } -export class Earth { } +// export class World { } +// export class Earth { } // export class Earth { } // export declare const Hello: World & Earth; @@ -12,86 +12,45 @@ export class Earth { } //--------------------------------------------------------- -// #region Type parameters (generics) -// /** -// * Some general comment about function. - -/** - * Bla bla - * - * @template T something wwegweg - * @template P something wegweg - * @param parameter1 wegweg - * @param parameter2 wegweweg - * @returns wegweg - */ -export function FunctionWithMultipleTypeParameters(parameter1: T, parameter2: P): string { - return "bar"; -} - -/** - * Some general comment about AnotherBar function. - */ -export function FunctionWithTypeParameterDefault(parameter1: string, parameter2: T): string { - return "bar"; -} - -/** - * Some general comment about AnotherBar function. - */ -export function FunctionWithTypeParameterConstraint(parameter1: string, parameter2: T): string { - return "bar"; -} - -export function AnotherFoo>(parameter1: string, parameter2: Promise): string { - return "bar"; -} -// #endregion Type parameters (generics) - - // #region Parameters -export function FunctionWithOneParameter(parameter: string) { } -export function FunctionWithNoParameters() { } - -export function FunctionWithMultipleParameters(parameter1: string, parameter2: number) { } // #endregion Parameters -export function Foo(): string { - return "foo"; -} +// export function Foo(): string { +// return "foo"; +// } -/** - * Some general comment about Bar function. - * - * @beta Some comment on beta. - * @deprecated - */ -export function Bar(parameter1: string, parameter2: number): string { - return "bar"; -} +// /** +// * Some general comment about Bar function. +// * +// * @beta Some comment on beta. +// * @deprecated +// */ +// export function Bar(parameter1: string, parameter2: number): string { +// return "bar"; +// } // #region Return types -export function FunctionWithoutReturnType>(parameter1: string, parameter2: Promise) { - return "bar"; -} +// export function FunctionWithoutReturnType>(parameter1: string, parameter2: Promise) { +// return "bar"; +// } -export function FunctionWithGenericReturnType(): Array { - return []; -} +// export function FunctionWithGenericReturnType(): Array { +// return []; +// } -export function FunctionWithPrimitiveReturnType(): boolean { - return true; -} +// export function FunctionWithPrimitiveReturnType(): boolean { +// return true; +// } -export function FunctionWithUnionReturnType(): "something" | "nothing" { - return "nothing"; -} +// export function FunctionWithUnionReturnType(): "something" | "nothing" { +// return "nothing"; +// } -export function FunctionWithIntersectionReturnType(): Earth & World { - return {}; -} +// export function FunctionWithIntersectionReturnType(): Earth & World { +// return {}; +// } // #endregion Return types // ------------------------------------------------------ @@ -120,11 +79,11 @@ export function FunctionWithIntersectionReturnType(): Earth & World { // anotherProperty: number; // } -// export function Funkcija(): T { -// return { -// myProperty: "asd" -// } as T; -// } +export function MyFunction(): T { + return { + myProperty: "sampleString" + } as T; +} // export interface MyInterface { // (param1: TValue, param2: TValue): boolean; @@ -150,68 +109,63 @@ export function FunctionWithIntersectionReturnType(): Earth & World { // 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" -} - -export enum Skaiciai { - Nulis = 0, - Vienas = 1, - Du = 2 -} +// /** +// * 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 Sarasas { - /** - * Pirmo description'as - */ - Pirmas, - /** - * Antro description'as - */ - Antras, - /** - * Trečio description'as - */ - Trecias -} +// export enum Skaiciai { +// Nulis = 0, +// Vienas = 1, +// Du = 2 +// } -export const enum ConstSkaiciai { - PirmasC = 0, - AntrasC = 1, - TreciasC = 2 -} +// export enum Sarasas { +// /** +// * Pirmo description'as +// */ +// Pirmas, +// /** +// * Antro description'as +// */ +// Antras, +// /** +// * Trečio description'as +// */ +// Trecias +// } -export const enum ConstSarasas { - /** - * Pirmo description'as - */ - PirmasC, - /** - * Antro description'as - */ - AntrasC, - /** - * Trečio description'as - */ - TreciasC -} +// export const enum ConstSkaiciai { +// PirmasC = 0, +// AntrasC = 1, +// TreciasC = 2 +// } -export const enum ConstUogos { - Jokie = "jokie", - Braskes = "braskes" -} +// export const enum ConstSarasas { +// /** +// * Pirmo description'as +// */ +// PirmasC, +// /** +// * Antro description'as +// */ +// AntrasC, +// /** +// * Trečio description'as +// */ +// TreciasC +// } // export interface Boo { // Boos: string[]; @@ -223,10 +177,6 @@ export const enum ConstUogos { // Type: TType; // } -// export async function GetFoo(): Promise { -// return; -// } - // export interface Bar extends Foo, Boo { // OtherStuff: string[]; // } @@ -248,15 +198,15 @@ export const enum ConstUogos { // public abstract Bar(): string; // } -/** - * @deprecated Use uogos instead ;) - */ -export type Hello = Uogos; - -export namespace FooNamespace { - export namespace BooNamespace { - export namespace BooNamespace2 { - export const Hello = "World!"; - } - } -} +// /** +// * @deprecated Use uogos instead ;) +// */ +// export type Hello = Uogos; + +// export namespace FooNamespace { +// export namespace BooNamespace { +// export namespace BooNamespace2 { +// export const Hello = "World!"; +// } +// } +// } diff --git a/packages/ts-docs-gen/tests/cases/simple-project-1/index.ts b/packages/ts-docs-gen/tests/cases/simple-project-1/index.ts index c3a40955..eeaf5349 100644 --- a/packages/ts-docs-gen/tests/cases/simple-project-1/index.ts +++ b/packages/ts-docs-gen/tests/cases/simple-project-1/index.ts @@ -1,3 +1,4 @@ +// #region Enums /** * Simple list. */ @@ -35,6 +36,8 @@ export enum EnumListWithStringValues { ThirdOption = "third" } +// #endregion Enums + export const SampleConst: string = "sample-const"; export class Foo { @@ -42,3 +45,96 @@ export class Foo { return message; } } + +export class World { } +export class Earth { } + +// #region Functions + +export function AnotherFoo(parameter1: string, parameter2: Promise): string { + return "bar"; +} + +export async function GetFoo(): Promise { + return; +} + +export function FunctionWithOneParameter(parameter: string): void { + return; +} + +export function FunctionWithNoParameters(): void { + return; +} + +export function FunctionWithMultipleParameters(parameter1: string, parameter2: number): void { + return; +} + +/** + * Some general comment about Bar function. + * + * @beta Some comment on beta. + * @deprecated + */ +export function Bar(parameter1: string, parameter2: number): string { + return "bar"; +} + +/** + * Comment on Function with multiple type parameters. + * + * @template T Parameter T comment + * @template P Parameter P comment + * @param parameter1 Parameter one comment + * @param parameter2 Parameter two comment + * @returns Return type comment + */ +export function FunctionWithMultipleTypeParameters(parameter1: T, parameter2: P): string { + return "bar"; +} + +/** + * Some general comment about Function with type parameter default function. + */ +export function FunctionWithTypeParameterDefault(parameter1: string, parameter2: T): string { + return "bar"; +} + +/** + * Some general comment about AnotherBar function. + */ +export function FunctionWithTypeParameterConstraint(parameter1: string, parameter2: T): string { + return "bar"; +} + +export function FunctionWithoutReturnType(parameter1: string, parameter2: Promise): string { + return "bar"; +} + +export function FunctionWithGenericReturnType(): string[] { + return []; +} + +export function FunctionWithPrimitiveReturnType(): boolean { + return true; +} + +export function FunctionWithUnionReturnType(): "something" | "nothing" { + return "nothing"; +} + +export function FunctionWithIntersectionReturnType(): Earth & World { + return {}; +} + +/** + * Function with TypeParameter as TypeLiteral. + */ +export function MyFunction(): T { + return { + myProperty: "sampleString" + } as T; +} + +// #endregion Functions From aaf3304f527bcfc85a712de7ab73d866da5a2a66 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Thu, 21 Dec 2017 16:11:39 +0200 Subject: [PATCH 24/26] index.md regenerated. --- .../examples/simple/docs/api/index.md | 41 +------------------ 1 file changed, 2 insertions(+), 39 deletions(-) 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 4acaee83..a0b13b83 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index.md @@ -1,44 +1,7 @@ -[ClassDeclaration-1]: index.md#class-earth -[ClassDeclaration-0]: index.md#class-world -[EnumDeclaration-0]: index.md#uogos -[ModuleDeclaration-1]: index\boonamespace.md#boonamespace -## class: World - -## class: Earth - -## FunctionWithMultipleTypeParameters(parameter1, parameter2) - -Bla bla - -```typescript -function FunctionWithMultipleTypeParameters(parameter1: T, parameter2: P): string -``` - -### Type parameters - -| Name | Constraint type | -| ---- | --------------- | -| T | Object | -| P | | - -### Parameters - -| Name | Type | -| ---------- | ---- | -| parameter1 | T | -| parameter2 | P | - -### Return type - -string - - -## FunctionWithTypeParameterDefault(parameter1, parameter2) - -Some general comment about AnotherBar function. +## MyFunction() ```typescript -function FunctionWithTypeParameterDefault(parameter1: string, parameter2: T): string +function MyFunction(): T ``` ### Type parameters From 66a7722a4d7aa7d52bc77dc4ff61874e76c125b3 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Thu, 21 Dec 2017 16:11:54 +0200 Subject: [PATCH 25/26] @simplrjs/markdown updated. --- common/config/rush/npm-shrinkwrap.json | 10 +++++----- packages/ts-docs-gen/package.json | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/common/config/rush/npm-shrinkwrap.json b/common/config/rush/npm-shrinkwrap.json index d71ee5cf..e5fe5a84 100644 --- a/common/config/rush/npm-shrinkwrap.json +++ b/common/config/rush/npm-shrinkwrap.json @@ -23,9 +23,9 @@ }, "@rush-temp/ts-docs-gen": { "version": "file:projects/ts-docs-gen.tgz", - "integrity": "sha1-EOjVkNyk5eR6fdm0niJiuEltOls=", + "integrity": "sha1-IIM5lH+f0v1NDXEIhk/erutcOrQ=", "requires": { - "@simplrjs/markdown": "1.0.2", + "@simplrjs/markdown": "1.0.3", "@types/fs-extra": "4.0.7", "@types/jest": "21.1.9", "@types/sinon": "4.1.2", @@ -42,9 +42,9 @@ } }, "@simplrjs/markdown": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/@simplrjs/markdown/-/markdown-1.0.2.tgz", - "integrity": "sha512-iGfzFQwjvnGle/vKuGy8o9cDfLtj6AVSLybK0bNTG08T0FG2CZuRSG6PQBaCRwSV9Wqmxu+JjDryVyZNPdNTVQ==", + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@simplrjs/markdown/-/markdown-1.0.3.tgz", + "integrity": "sha512-QkC79ttUek7d9w1yysaETZnsD7WO7JOLCbAIX8kCAeZhMY/21ZRULWjb3Pl7SBm6QqqYTOnKl8rvikmbVaGtLA==", "requires": { "@types/string": "0.0.29", "string": "3.3.3" diff --git a/packages/ts-docs-gen/package.json b/packages/ts-docs-gen/package.json index 59d62ac7..32048ed8 100644 --- a/packages/ts-docs-gen/package.json +++ b/packages/ts-docs-gen/package.json @@ -15,7 +15,7 @@ "engine": "node >= 7.5.0", "author": "simplrjs (https://github.com/simplrjs)", "dependencies": { - "@simplrjs/markdown": "^1.0.2", + "@simplrjs/markdown": "^1.0.3", "@types/fs-extra": "^4.0.5", "fast-glob": "^1.0.1", "fs-extra": "^4.0.3", From efab87f9c1cd3529d8edf1689eff8f47ac194752 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Thu, 21 Dec 2017 16:19:37 +0200 Subject: [PATCH 26/26] Tests snapshot updated. --- .../examples/simple/docs/api/index.md | 6 +- .../simple-project-1.test.ts.snap | 277 ++++++++++++++++++ 2 files changed, 280 insertions(+), 3 deletions(-) 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 a0b13b83..af7b4273 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index.md @@ -6,9 +6,9 @@ function MyFunction(parameter1: string, parameter2: Promise): string", + "\`\`\`", + "", + "### Type parameters", + "", + "| Name | Constraint type |", + "| ---- | --------------- |", + "| T | Object |", + "", + "### Parameters", + "", + "| Name | Type |", + "| ---------- | ------- |", + "| parameter1 | string |", + "| parameter2 | Promise |", + "", + "### Return type", + "", + "string", + "", + "", + "## GetFoo()", + "", + "\`\`\`typescript", + "function GetFoo(): Promise", + "\`\`\`", + "", + "### Return type", + "", + "Promise", + "", + "", + "## 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 |", + "| ---------- | ---- |", + "| parameter1 | T |", + "| parameter2 | P |", + "", + "### 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 |", + "", + "### Parameters", + "", + "| Name | Type |", + "| ---------- | ------- |", + "| parameter1 | string |", + "| parameter2 | Promise |", + "", + "### Return type", + "", + "string", + "", + "", + "## FunctionWithGenericReturnType()", + "", + "\`\`\`typescript", + "function FunctionWithGenericReturnType(): string[]", + "\`\`\`", + "", + "### Return type", + "", + "Array", + "", + "", + "## 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", + "", + "", ], }, ]