From 7ccf81e04ed1a6a29b574c91e31bfa90354928d9 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Tue, 5 Dec 2017 22:41:16 +0200 Subject: [PATCH 01/13] `index.ts` updated with const enums. --- packages/ts-docs-gen/examples/simple/index.ts | 85 ++++++++++++++----- 1 file changed, 64 insertions(+), 21 deletions(-) diff --git a/packages/ts-docs-gen/examples/simple/index.ts b/packages/ts-docs-gen/examples/simple/index.ts index abb00c30..1fc25468 100644 --- a/packages/ts-docs-gen/examples/simple/index.ts +++ b/packages/ts-docs-gen/examples/simple/index.ts @@ -1,13 +1,13 @@ // tslint:disable -import { Foo } from "./exported-functions"; +// import { Foo } from "./exported-functions"; -export class World { } -export class Earth { } +// export class World { } +// export class Earth { } -export declare const Hello: World & Earth; +// export declare const Hello: World & Earth; -export const FooFunc = Foo; +// export const FooFunc = Foo; // export function Foo(): string { // return "foo"; @@ -71,22 +71,65 @@ export const FooFunc = Foo; // export const name = "some-kind-of-module"; // } -// export enum Uogos { -// Jokie = "jokie", -// Braskes = "braskes" -// } - -// export enum Skaiciai { -// Nulis = 0, -// Vienas = 1, -// Du = 2 -// } - -// export enum Sarasas { -// Pirmas, -// Antras, -// Trecias -// } +/** + * Some information. + * 2nd 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 +} + +export enum Sarasas { + /** + * Pirmo description'as + */ + Pirmas, + /** + * Antro description'as + */ + Antras, + /** + * Trečio description'as + */ + Trecias +} + +export const enum ConstSkaiciai { + PirmasC = 0, + AntrasC = 1, + TreciasC = 2 +} + +export const enum ConstSarasas { + /** + * Pirmo description'as + */ + PirmasC, + /** + * Antro description'as + */ + AntrasC, + /** + * Trečio description'as + */ + TreciasC +} + +export const enum ConstUogos { + Jokie = "jokie", + Braskes = "braskes" +} // export interface Boo { // Boos: string[]; From 56e78f8bd7cb070e4338774d13252930ab4dff2b Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Tue, 5 Dec 2017 22:42:30 +0200 Subject: [PATCH 02/13] ExtractedData added to PluginData. --- packages/ts-docs-gen/src/contracts/plugin-data.ts | 4 +++- packages/ts-docs-gen/src/generator.ts | 3 +++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/packages/ts-docs-gen/src/contracts/plugin-data.ts b/packages/ts-docs-gen/src/contracts/plugin-data.ts index 6d9845c8..e3315a02 100644 --- a/packages/ts-docs-gen/src/contracts/plugin-data.ts +++ b/packages/ts-docs-gen/src/contracts/plugin-data.ts @@ -1,9 +1,11 @@ +import { Contracts, ExtractDto } from "ts-extractor"; + import { ReferenceTuple } from "./reference-tuple"; import { RenderItemOutputDto } from "./render-item-output-dto"; -import { Contracts } from "ts-extractor"; export interface PluginData { Reference: ReferenceTuple; ApiItem: TKind; + ExtractedData: ExtractDto; GetItem(entryFile: Contracts.ApiSourceFileDto, reference: ReferenceTuple): RenderItemOutputDto; } diff --git a/packages/ts-docs-gen/src/generator.ts b/packages/ts-docs-gen/src/generator.ts index 8d089c27..35ffa6cd 100644 --- a/packages/ts-docs-gen/src/generator.ts +++ b/packages/ts-docs-gen/src/generator.ts @@ -1,3 +1,4 @@ + import { Contracts } from "ts-extractor"; import * as path from "path"; import * as fs from "fs-extra"; @@ -78,6 +79,7 @@ export class Generator { for (const plugin of plugins) { if (plugin.CheckApiItem(apiItem)) { return plugin.Render({ + ExtractedData: this.configuration.ExtractedData, Reference: reference, ApiItem: apiItem, GetItem: this.getRenderedItemByReference @@ -87,6 +89,7 @@ export class Generator { const defaultPlugin = new ApiDefaultPlugin(); return defaultPlugin.Render({ + ExtractedData: this.configuration.ExtractedData, Reference: reference, ApiItem: apiItem, GetItem: this.getRenderedItemByReference From f1dea67145c397de6777e033799196e165fab0ae Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Tue, 5 Dec 2017 22:42:50 +0200 Subject: [PATCH 03/13] Tab function added to ExtractorHelpers. --- packages/ts-docs-gen/src/extractor-helpers.ts | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/packages/ts-docs-gen/src/extractor-helpers.ts b/packages/ts-docs-gen/src/extractor-helpers.ts index 7b9d7af4..a5e9fe48 100644 --- a/packages/ts-docs-gen/src/extractor-helpers.ts +++ b/packages/ts-docs-gen/src/extractor-helpers.ts @@ -44,4 +44,16 @@ export namespace ExtractorHelpers { return `${item.VariableDeclarationType} ${name}: ${item.Type.Text};`; } + + // TODO: reconsider location + 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; + } + // --------------------------------------------------- } From ee39982691c5ffef3a707fae46c08dcf9a191b0f Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Tue, 5 Dec 2017 22:43:08 +0200 Subject: [PATCH 04/13] ApiEnumPlugin created. --- .../src/plugins/api-enum-plugin.ts | 124 ++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 packages/ts-docs-gen/src/plugins/api-enum-plugin.ts diff --git a/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts b/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts new file mode 100644 index 00000000..dd74fc64 --- /dev/null +++ b/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts @@ -0,0 +1,124 @@ +import { Contracts, ExtractDto } from "ts-extractor"; +import { MarkdownGenerator } from "@simplrjs/markdown"; + +import { ApiItemPluginBase } from "../abstractions/api-item-plugin-base"; +import { SupportedApiItemKindType } from "../contracts/supported-api-item-kind-type"; +import { PluginData } from "../contracts/plugin-data"; +import { RenderItemOutputDto } from "../contracts/render-item-output-dto"; +import { ExtractorHelpers } from "../extractor-helpers"; + +// TODO: const enums implementation. +export class ApiEnumPlugin extends ApiItemPluginBase { + public SupportedApiItemsKinds(): SupportedApiItemKindType[] { + return [this.SupportKind.Enum]; + } + + // TODO: implement @deprecated and @beta. + private resolveDocumentationComment(metaData: Contracts.ApiMetadataDto): string[] { + if (metaData.DocumentationComment.length === 0) { + return []; + } + + return metaData.DocumentationComment.map(commentItem => commentItem.text); + } + + // TODO: move to extractor helpers. + private reconstructEnumCode(alias: string, memberItems: Contracts.ApiEnumMemberDto[]): string[] { + const membersStrings = memberItems.map((memberItem, index, array) => { + let memberString = `${ExtractorHelpers.Tab()} ${memberItem.Name}`; + + if (memberItem.Value) { + memberString += ` = ${memberItem.Value}`; + } + + // Checking if current item is not the last item + if (index !== memberItems.length - 1) { + memberString += ","; + } + + return memberString; + }); + + return [ + `enum ${alias} {`, + ...membersStrings, + "}" + ]; + } + + private constructEnumTable(members: Contracts.ApiEnumMemberDto[]): string[] { + const header = ["Name", "Value"]; + + let descriptionFound = false; + const content = members.map(member => { + const row: string[] = [member.Name, member.Value]; + const comments = member.Metadata.DocumentationComment; + + if (comments.length > 0) { + descriptionFound = true; + + const commentSeparator = " "; + let description = ""; + + // TODO: add '.' if needed. + comments.forEach((comment, index, array) => { + description += comment.text; + + if (index !== array.length - 1) { + description += commentSeparator; + } + }); + + row.push(description); + } + + return row; + }); + + if (descriptionFound) { + header.push("Description"); + } + + return MarkdownGenerator.table(header, content); + } + + 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 heading = MarkdownGenerator.header(alias, 2); + + const enumMembers = this.getEnumMembers(data.ApiItem.Members, data.ExtractedData); + + // TODO: move MarkdownGenerator code option to helpers. + const output: string[] = [ + heading, + "", + ...this.resolveDocumentationComment(data.ApiItem.Metadata), + "", + ...MarkdownGenerator.code(this.reconstructEnumCode(alias, enumMembers), { lang: "typescript" }), + "", + ...this.constructEnumTable(enumMembers) + ]; + + return { + Heading: "Enum", + ApiItem: data.ApiItem, + References: [], + RenderOutput: output + }; + } +} From 30d39f36280fe572e5774a7d2eb060b4b891d4eb Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Tue, 5 Dec 2017 22:43:19 +0200 Subject: [PATCH 05/13] ApiEnumPlugin implemented. --- 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 b6d52aea..a291cba3 100644 --- a/packages/ts-docs-gen/src/default-plugins.ts +++ b/packages/ts-docs-gen/src/default-plugins.ts @@ -1,5 +1,7 @@ import { ApiVariablePlugin } from "./plugins/api-variable-plugin"; +import { ApiEnumPlugin } from "./plugins/api-enum-plugin"; export const DefaultPlugins = [ - new ApiVariablePlugin() + new ApiVariablePlugin(), + new ApiEnumPlugin() ]; From 54fa2143d9ac8554b2a654269fecdfc224b0ff41 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Wed, 6 Dec 2017 17:11:35 +0200 Subject: [PATCH 06/13] ReconstructEnumCode method moved to `extractor-helpers.ts`. --- packages/ts-docs-gen/src/extractor-helpers.ts | 40 ++++++++++++++ .../src/plugins/api-enum-plugin.ts | 54 +++++++++---------- 2 files changed, 66 insertions(+), 28 deletions(-) diff --git a/packages/ts-docs-gen/src/extractor-helpers.ts b/packages/ts-docs-gen/src/extractor-helpers.ts index a5e9fe48..a505882b 100644 --- a/packages/ts-docs-gen/src/extractor-helpers.ts +++ b/packages/ts-docs-gen/src/extractor-helpers.ts @@ -45,6 +45,29 @@ export namespace ExtractorHelpers { return `${item.VariableDeclarationType} ${name}: ${item.Type.Text};`; } + export function ReconstructEnumCode(alias: string, memberItems: Contracts.ApiEnumMemberDto[]): string[] { + const membersStrings = memberItems.map((memberItem, index, array) => { + let memberString = `${ExtractorHelpers.Tab()} ${memberItem.Name}`; + + if (memberItem.Value) { + memberString += ` = ${memberItem.Value}`; + } + + // Checking if current item is not the last item + if (index !== memberItems.length - 1) { + memberString += ","; + } + + return memberString; + }); + + return [ + `enum ${alias} {`, + ...membersStrings, + "}" + ]; + } + // TODO: reconsider location const TAB_STRING = " "; @@ -56,4 +79,21 @@ 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 = ".!:;,-"; + + const lastSymbol = trimmedSentence[trimmedSentence.length - 1]; + + if (punctuationMarks.indexOf(lastSymbol) !== -1) { + return trimmedSentence; + } + + return trimmedSentence + punctuationMark; + } } 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 dd74fc64..7e62866d 100644 --- a/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts @@ -13,56 +13,52 @@ export class ApiEnumPlugin extends ApiItemPluginBase { return [this.SupportKind.Enum]; } - // TODO: implement @deprecated and @beta. private resolveDocumentationComment(metaData: Contracts.ApiMetadataDto): string[] { if (metaData.DocumentationComment.length === 0) { return []; } - return metaData.DocumentationComment.map(commentItem => commentItem.text); + // TODO: implement ExtractorHelpers.FixSentence when comments separation implemented in `ts-extractor`. + return metaData.DocumentationComment.map(commentItem => ExtractorHelpers.FixSentence(commentItem.text)); } - // TODO: move to extractor helpers. - private reconstructEnumCode(alias: string, memberItems: Contracts.ApiEnumMemberDto[]): string[] { - const membersStrings = memberItems.map((memberItem, index, array) => { - let memberString = `${ExtractorHelpers.Tab()} ${memberItem.Name}`; - - if (memberItem.Value) { - memberString += ` = ${memberItem.Value}`; - } - - // Checking if current item is not the last item - if (index !== memberItems.length - 1) { - memberString += ","; - } - - return memberString; - }); - - return [ - `enum ${alias} {`, - ...membersStrings, - "}" - ]; + /** + * Resolves "@beta" and "@deprecated" JSDocTags. + */ + private resolveJSDocTags(metaData: Contracts.ApiMetadataDto): string[] { + return metaData.JSDocTags + .filter(tag => tag.name === "deprecated" || tag.name === "beta") + .map(tag => { + if (tag.text) { + return `${tag.name} - ${tag.text}`; + } + + return tag.name; + }); } private constructEnumTable(members: Contracts.ApiEnumMemberDto[]): string[] { + // Table header. const header = ["Name", "Value"]; + // Assuming that enum members are not described separately. let descriptionFound = false; + + // Generating table content. const content = members.map(member => { const row: string[] = [member.Name, member.Value]; const comments = member.Metadata.DocumentationComment; + // Handling enum member comments. if (comments.length > 0) { descriptionFound = true; const commentSeparator = " "; let description = ""; - // TODO: add '.' if needed. + // Reducing comments into a single description. comments.forEach((comment, index, array) => { - description += comment.text; + description += ExtractorHelpers.FixSentence(comment.text); if (index !== array.length - 1) { description += commentSeparator; @@ -75,6 +71,7 @@ export class ApiEnumPlugin extends ApiItemPluginBase { return row; }); + // Add description cell in header if at least one enum member have comment. if (descriptionFound) { header.push("Description"); } @@ -103,13 +100,14 @@ export class ApiEnumPlugin extends ApiItemPluginBase { const enumMembers = this.getEnumMembers(data.ApiItem.Members, data.ExtractedData); - // TODO: move MarkdownGenerator code option to helpers. const output: string[] = [ heading, "", ...this.resolveDocumentationComment(data.ApiItem.Metadata), "", - ...MarkdownGenerator.code(this.reconstructEnumCode(alias, enumMembers), { lang: "typescript" }), + ...this.resolveJSDocTags(data.ApiItem.Metadata), + "", + ...MarkdownGenerator.code(ExtractorHelpers.ReconstructEnumCode(alias, enumMembers), ExtractorHelpers.DEFAULT_CODE_OPTIONS), "", ...this.constructEnumTable(enumMembers) ]; From 419fd50ab79c9038c13b56dca50f535089827cf6 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Wed, 6 Dec 2017 17:14:20 +0200 Subject: [PATCH 07/13] Markdown generation code options in ApiVariablePlugin changed to use options from ExtractorHelpers. --- packages/ts-docs-gen/src/plugins/api-variable-plugin.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/ts-docs-gen/src/plugins/api-variable-plugin.ts b/packages/ts-docs-gen/src/plugins/api-variable-plugin.ts index 05765cc5..4c3d21c0 100644 --- a/packages/ts-docs-gen/src/plugins/api-variable-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-variable-plugin.ts @@ -33,7 +33,7 @@ export class ApiVariablePlugin extends ApiItemPluginBase Date: Wed, 6 Dec 2017 17:14:54 +0200 Subject: [PATCH 08/13] Simple example updated. --- .../examples/simple/docs/api/index.md | 42 ++++++++++++------- packages/ts-docs-gen/examples/simple/index.ts | 19 +++++---- 2 files changed, 39 insertions(+), 22 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 a0f98148..99351bf8 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index.md @@ -1,28 +1,42 @@ -[ClassDeclaration-0]: index.md#class-world -[ClassDeclaration-1]: index.md#class-earth -[FunctionDeclaration-0]: exported-functions.md#function-foo # index -## class: World +## Uogos -## class: Earth +Some information +2nd line of some information +3rd line of some information +4th line of some information +5th line of some information. -## Hello +deprecated +beta ```typescript -const Hello: World & Earth; +enum Uogos { + Jokie = "jokie", + Braskes = "braskes" +} ``` -### Type +| Name | Value | +| ------- | --------- | +| Jokie | "jokie" | +| Braskes | "braskes" | + +## Sarasas -[World][ClassDeclaration-0] & [Earth][ClassDeclaration-1] -## FooFunc ```typescript -const FooFunc: () => string; +enum Sarasas { + Pirmas = 0, + Antras = 1, + Trecias = 2 +} ``` -### Type - -[Foo][FunctionDeclaration-0] +| Name | Value | Description | +| ------- | ----- | ---------------------- | +| Pirmas | 0 | Pirmo description'as. | +| Antras | 1 | Antro description'as. | +| Trecias | 2 | Trečio description'as. | diff --git a/packages/ts-docs-gen/examples/simple/index.ts b/packages/ts-docs-gen/examples/simple/index.ts index 1fc25468..63042ba2 100644 --- a/packages/ts-docs-gen/examples/simple/index.ts +++ b/packages/ts-docs-gen/examples/simple/index.ts @@ -51,12 +51,12 @@ // (param1: TValue, param2: TValue): boolean; // } -/** - * Some JSdoc information. - * 2nd line of some JSdoc information. - * @summary Some summary about this package version. - * @summary 2nd of some summary about this package version. - */ +// /** +// * Some JSdoc information. +// * 2nd line of some JSdoc information. +// * @summary Some summary about this package version. +// * @summary 2nd of some summary about this package version. +// */ // export const itemsList: string[] = ["a"]; // export function Ok(isIt: boolean): boolean { @@ -72,8 +72,11 @@ // } /** - * Some information. - * 2nd line of some information. + * 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 From 8a0637a53ec19a82a975b08870c8f38e3192663e Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Wed, 6 Dec 2017 17:37:28 +0200 Subject: [PATCH 09/13] Test case SimpleProject1 updated to use ApiEnumPlugin and ApiVariablePlugin. --- .../examples/simple/docs/api/index.md | 70 +++++++++++++++++++ .../simple-project-1.test.ts.snap | 68 ++++++++++++++++++ .../simple-project-2.test.ts.snap | 2 + .../tests/cases/simple-project-1/index.ts | 39 +++++++++++ 4 files changed, 179 insertions(+) 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 99351bf8..8c08ae16 100644 --- a/packages/ts-docs-gen/examples/simple/docs/api/index.md +++ b/packages/ts-docs-gen/examples/simple/docs/api/index.md @@ -23,6 +23,24 @@ enum Uogos { | Jokie | "jokie" | | Braskes | "braskes" | +## Skaiciai + + + +```typescript +enum Skaiciai { + Nulis = 0, + Vienas = 1, + Du = 2 +} +``` + +| Name | Value | +| ------ | ----- | +| Nulis | 0 | +| Vienas | 1 | +| Du | 2 | + ## Sarasas @@ -40,3 +58,55 @@ enum Sarasas { | 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" | 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 1b490680..9113bab0 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 @@ -7,6 +7,74 @@ Array [ "Output": Array [ "# index", "", + "## EnumList", + "", + "Simple list.", + "", + "", + "\`\`\`typescript", + "enum EnumList {", + " FirstOption = 0,", + " SecondOption = 1,", + " ThirdOption = 2", + "}", + "\`\`\`", + "", + "| Name | Value | Description |", + "| ------------ | ----- | ------------------------------ |", + "| FirstOption | 0 | Description for First option. |", + "| SecondOption | 1 | Description for Second option. |", + "| ThirdOption | 2 | Description for Third option. |", + "", + "## EnumListWithNumberValues", + "", + "List with number values with no punctuation at the end of description.", + "", + "", + "\`\`\`typescript", + "enum EnumListWithNumberValues {", + " FirstOption = 1,", + " SecondOption = 2,", + " ThirdOption = 3", + "}", + "\`\`\`", + "", + "| Name | Value |", + "| ------------ | ----- |", + "| FirstOption | 1 |", + "| SecondOption | 2 |", + "| ThirdOption | 3 |", + "", + "## EnumListWithStringValues", + "", + "", + "beta", + "deprecated", + "", + "\`\`\`typescript", + "enum EnumListWithStringValues {", + " FirstOption = \\"first\\",", + " SecondOption = \\"second\\",", + " ThirdOption = \\"third\\"", + "}", + "\`\`\`", + "", + "| Name | Value |", + "| ------------ | -------- |", + "| FirstOption | \\"first\\" |", + "| SecondOption | \\"second\\" |", + "| ThirdOption | \\"third\\" |", + "", + "## SampleConst", + "", + "\`\`\`typescript", + "const SampleConst: string;", + "\`\`\`", + "", + "### Type", + "", + "string", + "", "## class: Foo", "", ], 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 387ccdc0..4939fde2 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 @@ -7,6 +7,8 @@ Array [ "Output": Array [ "# index", "", + "## class: Foo", + "", "## class: FooStart", "", ], 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 0286763e..c3a40955 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,42 @@ +/** + * Simple list. + */ +export enum EnumList { + /** + * Description for First option. + */ + FirstOption, + /** + * Description for Second option. + */ + SecondOption, + /** + * Description for Third option. + */ + ThirdOption +} + +/** + * List with number values with no punctuation at the end of description + */ +export enum EnumListWithNumberValues { + FirstOption = 1, + SecondOption = 2, + ThirdOption = 3 +} + +/** + * @beta + * @deprecated + */ +export enum EnumListWithStringValues { + FirstOption = "first", + SecondOption = "second", + ThirdOption = "third" +} + +export const SampleConst: string = "sample-const"; + export class Foo { public HandleMessage(message: string): string { return message; From 406ee52dd19a8271cd9a26db934747a273cb0228 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Wed, 6 Dec 2017 17:40:34 +0200 Subject: [PATCH 10/13] JsDocTag output text TODO added . --- packages/ts-docs-gen/src/plugins/api-enum-plugin.ts | 1 + 1 file changed, 1 insertion(+) 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 7e62866d..6c8b6503 100644 --- a/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts @@ -22,6 +22,7 @@ export class ApiEnumPlugin extends ApiItemPluginBase { return metaData.DocumentationComment.map(commentItem => ExtractorHelpers.FixSentence(commentItem.text)); } + // TODO: improve output text of @beta and @deprecated JSDocTags. /** * Resolves "@beta" and "@deprecated" JSDocTags. */ From a5dff3ad2910cab965b0be2c3832a70fbce5e758 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Wed, 6 Dec 2017 18:01:16 +0200 Subject: [PATCH 11/13] Some missing comments added. --- packages/ts-docs-gen/src/extractor-helpers.ts | 6 +++++- packages/ts-docs-gen/src/plugins/api-enum-plugin.ts | 5 ++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/packages/ts-docs-gen/src/extractor-helpers.ts b/packages/ts-docs-gen/src/extractor-helpers.ts index a505882b..c5bd13d7 100644 --- a/packages/ts-docs-gen/src/extractor-helpers.ts +++ b/packages/ts-docs-gen/src/extractor-helpers.ts @@ -46,14 +46,17 @@ export namespace ExtractorHelpers { } 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}`; } - // Checking if current item is not the last item + // Add a comma if current item is not the last item if (index !== memberItems.length - 1) { memberString += ","; } @@ -61,6 +64,7 @@ export namespace ExtractorHelpers { return memberString; }); + // Construct enum code output return [ `enum ${alias} {`, ...membersStrings, 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 6c8b6503..b77ec119 100644 --- a/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts @@ -19,7 +19,7 @@ export class ApiEnumPlugin extends ApiItemPluginBase { } // TODO: implement ExtractorHelpers.FixSentence when comments separation implemented in `ts-extractor`. - return metaData.DocumentationComment.map(commentItem => ExtractorHelpers.FixSentence(commentItem.text)); + return metaData.DocumentationComment.map(commentItem => commentItem.text); } // TODO: improve output text of @beta and @deprecated JSDocTags. @@ -80,6 +80,9 @@ 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[] = []; From 690c3c78b8991202956f7dfc9160e752e347c5e2 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Wed, 6 Dec 2017 19:43:57 +0200 Subject: [PATCH 12/13] New version of SimplrJS Markdown installed. --- common/config/rush/npm-shrinkwrap.json | 32 +++++++++++++------------- packages/ts-docs-gen/package.json | 2 +- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/common/config/rush/npm-shrinkwrap.json b/common/config/rush/npm-shrinkwrap.json index 1c68428e..1915ea3f 100644 --- a/common/config/rush/npm-shrinkwrap.json +++ b/common/config/rush/npm-shrinkwrap.json @@ -8,9 +8,9 @@ "resolved": "file:projects\\ts-docs-gen.tgz" }, "@simplrjs/markdown": { - "version": "0.1.0-beta", - "from": "@simplrjs/markdown@0.1.0-beta", - "resolved": "https://registry.npmjs.org/@simplrjs/markdown/-/markdown-0.1.0-beta.tgz" + "version": "1.0.0", + "from": "@simplrjs/markdown@>=1.0.0 <2.0.0", + "resolved": "https://registry.npmjs.org/@simplrjs/markdown/-/markdown-1.0.0.tgz" }, "@types/fs-extra": { "version": "4.0.5", @@ -23,9 +23,9 @@ "resolved": "https://registry.npmjs.org/@types/jest/-/jest-21.1.8.tgz" }, "@types/node": { - "version": "8.0.53", + "version": "8.0.55", "from": "@types/node@*", - "resolved": "https://registry.npmjs.org/@types/node/-/node-8.0.53.tgz" + "resolved": "https://registry.npmjs.org/@types/node/-/node-8.0.55.tgz" }, "@types/sinon": { "version": "4.0.0", @@ -33,9 +33,9 @@ "resolved": "https://registry.npmjs.org/@types/sinon/-/sinon-4.0.0.tgz" }, "@types/string": { - "version": "0.0.28", - "from": "@types/string@0.0.28", - "resolved": "https://registry.npmjs.org/@types/string/-/string-0.0.28.tgz" + "version": "0.0.29", + "from": "@types/string@0.0.29", + "resolved": "https://registry.npmjs.org/@types/string/-/string-0.0.29.tgz" }, "abab": { "version": "1.0.4", @@ -53,9 +53,9 @@ "resolved": "https://registry.npmjs.org/acorn-globals/-/acorn-globals-3.1.0.tgz" }, "ajv": { - "version": "5.5.0", + "version": "5.5.1", "from": "ajv@>=5.1.0 <6.0.0", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-5.5.0.tgz" + "resolved": "https://registry.npmjs.org/ajv/-/ajv-5.5.1.tgz" }, "amdefine": { "version": "1.0.1", @@ -861,9 +861,9 @@ "resolved": "https://registry.npmjs.org/fragment-cache/-/fragment-cache-0.2.1.tgz" }, "fs-extra": { - "version": "4.0.2", + "version": "4.0.3", "from": "fs-extra@>=4.0.2 <5.0.0", - "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-4.0.2.tgz" + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-4.0.3.tgz" }, "fs.realpath": { "version": "1.0.0", @@ -1669,9 +1669,9 @@ "resolved": "https://registry.npmjs.org/just-extend/-/just-extend-1.1.27.tgz" }, "kind-of": { - "version": "6.0.1", + "version": "6.0.2", "from": "kind-of@>=6.0.0 <7.0.0", - "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.1.tgz" + "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.2.tgz" }, "lazy-cache": { "version": "2.0.2", @@ -2717,9 +2717,9 @@ } }, "ts-jest": { - "version": "21.2.3", + "version": "21.2.4", "from": "ts-jest@>=21.2.3 <22.0.0", - "resolved": "https://registry.npmjs.org/ts-jest/-/ts-jest-21.2.3.tgz", + "resolved": "https://registry.npmjs.org/ts-jest/-/ts-jest-21.2.4.tgz", "dependencies": { "source-map": { "version": "0.6.1", diff --git a/packages/ts-docs-gen/package.json b/packages/ts-docs-gen/package.json index 32a6c5fc..674499a1 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": "0.1.0-beta", + "@simplrjs/markdown": "^1.0.0", "@types/fs-extra": "^4.0.5", "fast-glob": "^1.0.1", "fs-extra": "^4.0.2", From abb1b1ec440dd9729ee12278c08790743f384ef3 Mon Sep 17 00:00:00 2001 From: Deividas Bakanas Date: Wed, 6 Dec 2017 19:44:50 +0200 Subject: [PATCH 13/13] @simplrjs/markdown breaking changes resolved. --- packages/ts-docs-gen/src/file-manager.ts | 4 +- packages/ts-docs-gen/src/generator-helpers.ts | 2 +- .../src/plugins/api-default-plugin.ts | 2 +- .../src/plugins/api-enum-plugin.ts | 31 +++++++--------- .../src/plugins/api-variable-plugin.ts | 37 ++++++++----------- 5 files changed, 32 insertions(+), 44 deletions(-) diff --git a/packages/ts-docs-gen/src/file-manager.ts b/packages/ts-docs-gen/src/file-manager.ts index 40892827..d0c55974 100644 --- a/packages/ts-docs-gen/src/file-manager.ts +++ b/packages/ts-docs-gen/src/file-manager.ts @@ -21,7 +21,7 @@ export class FileManager extends FileManagerBaseBase { const heading = path.basename(entryFile.Name, path.extname(entryFile.Name)); const output: string[] = [ - MarkdownGenerator.header(`${heading}`, 1) + MarkdownGenerator.Header(`${heading}`, 1) ]; return { @@ -61,7 +61,7 @@ export class FileManager extends FileManagerBaseBase { item.References .forEach(referenceId => references.push( - MarkdownGenerator.linkDefinition(referenceId, this.referenceToFile.get(referenceId) || "#__error") + MarkdownGenerator.LinkDefinition(referenceId, this.referenceToFile.get(referenceId) || "#__error") ) ); } diff --git a/packages/ts-docs-gen/src/generator-helpers.ts b/packages/ts-docs-gen/src/generator-helpers.ts index 7f15fd6b..4e01ecc8 100644 --- a/packages/ts-docs-gen/src/generator-helpers.ts +++ b/packages/ts-docs-gen/src/generator-helpers.ts @@ -33,7 +33,7 @@ export namespace GeneratorHelpers { references.push(type.ReferenceId); // Link to definition - text = `${MarkdownGenerator.link(type.Name || "???", type.ReferenceId, true)}`; + text = `${MarkdownGenerator.Link(type.Name || "???", type.ReferenceId, true)}`; // Generics if (type.Generics != null) { diff --git a/packages/ts-docs-gen/src/plugins/api-default-plugin.ts b/packages/ts-docs-gen/src/plugins/api-default-plugin.ts index 0aa5c753..93001e90 100644 --- a/packages/ts-docs-gen/src/plugins/api-default-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-default-plugin.ts @@ -14,7 +14,7 @@ export class ApiDefaultPlugin extends ApiItemPluginBase { const [, alias] = data.Reference; const heading = `${data.ApiItem.ApiKind}: ${alias}`; const output: string[] = [ - MarkdownGenerator.header(heading, 2) + MarkdownGenerator.Header(heading, 2) ]; return { 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 b77ec119..4b9a31a8 100644 --- a/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-enum-plugin.ts @@ -1,5 +1,5 @@ import { Contracts, ExtractDto } from "ts-extractor"; -import { MarkdownGenerator } from "@simplrjs/markdown"; +import { MarkdownGenerator, MarkdownBuilder } from "@simplrjs/markdown"; import { ApiItemPluginBase } from "../abstractions/api-item-plugin-base"; import { SupportedApiItemKindType } from "../contracts/supported-api-item-kind-type"; @@ -77,7 +77,7 @@ export class ApiEnumPlugin extends ApiItemPluginBase { header.push("Description"); } - return MarkdownGenerator.table(header, content); + return MarkdownGenerator.Table(header, content); } /** @@ -99,28 +99,23 @@ export class ApiEnumPlugin extends ApiItemPluginBase { public Render(data: PluginData): RenderItemOutputDto { const [, alias] = data.Reference; - - const heading = MarkdownGenerator.header(alias, 2); - const enumMembers = this.getEnumMembers(data.ApiItem.Members, data.ExtractedData); - - const output: string[] = [ - heading, - "", - ...this.resolveDocumentationComment(data.ApiItem.Metadata), - "", - ...this.resolveJSDocTags(data.ApiItem.Metadata), - "", - ...MarkdownGenerator.code(ExtractorHelpers.ReconstructEnumCode(alias, enumMembers), ExtractorHelpers.DEFAULT_CODE_OPTIONS), - "", - ...this.constructEnumTable(enumMembers) - ]; + const builder = new MarkdownBuilder() + .Header(alias, 2) + .EmptyLine() + .Text(this.resolveDocumentationComment(data.ApiItem.Metadata)) + .EmptyLine() + .Text(this.resolveJSDocTags(data.ApiItem.Metadata)) + .EmptyLine() + .Code(ExtractorHelpers.ReconstructEnumCode(alias, enumMembers), ExtractorHelpers.DEFAULT_CODE_OPTIONS) + .EmptyLine() + .Text(this.constructEnumTable(enumMembers)); return { Heading: "Enum", ApiItem: data.ApiItem, References: [], - RenderOutput: output + RenderOutput: builder.GetOutput() }; } } diff --git a/packages/ts-docs-gen/src/plugins/api-variable-plugin.ts b/packages/ts-docs-gen/src/plugins/api-variable-plugin.ts index 4c3d21c0..1ad4c45e 100644 --- a/packages/ts-docs-gen/src/plugins/api-variable-plugin.ts +++ b/packages/ts-docs-gen/src/plugins/api-variable-plugin.ts @@ -1,5 +1,5 @@ import { Contracts } from "ts-extractor"; -import { MarkdownGenerator } from "@simplrjs/markdown"; +import { MarkdownBuilder } from "@simplrjs/markdown"; import { ApiItemPluginBase } from "../abstractions/api-item-plugin-base"; import { SupportedApiItemKindType } from "../contracts/supported-api-item-kind-type"; @@ -15,36 +15,29 @@ export class ApiVariablePlugin extends ApiItemPluginBase): RenderItemOutputDto { const [, alias] = data.Reference; - let references: string[] = []; const heading = alias; + const typeStringDto = GeneratorHelpers.TypeDtoToMarkdownString(data.ApiItem.Type); + + const builder = new MarkdownBuilder() + .Header(heading, 2) + .EmptyLine(); - let documentationComment: string[] = []; if (data.ApiItem.Metadata.DocumentationComment.length > 0) { - documentationComment = [ - ...data.ApiItem.Metadata.DocumentationComment.map(x => x.text), - "" - ]; + builder.Text(data.ApiItem.Metadata.DocumentationComment.map(x => x.text)); } - const typeStringDto = GeneratorHelpers.TypeDtoToMarkdownString(data.ApiItem.Type); - references = references.concat(typeStringDto.References); - - const output: string[] = [ - MarkdownGenerator.header(heading, 2), - "", - ...documentationComment, - ...MarkdownGenerator.code(ExtractorHelpers.ApiVariableToString(data.ApiItem), ExtractorHelpers.DEFAULT_CODE_OPTIONS), - "", - MarkdownGenerator.header("Type", 3), - "", - typeStringDto.Text - ]; + builder + .Code(ExtractorHelpers.ApiVariableToString(data.ApiItem), ExtractorHelpers.DEFAULT_CODE_OPTIONS) + .EmptyLine() + .Header("Type", 3) + .EmptyLine() + .Text(typeStringDto.Text); return { Heading: heading, ApiItem: data.ApiItem, - References: references, - RenderOutput: output + References: typeStringDto.References, + RenderOutput: builder.GetOutput() }; } }