From 5b87c9dd82a7f173f623c82a6ec345cd8ea5369e Mon Sep 17 00:00:00 2001 From: "Adam A. Zerella" Date: Wed, 13 Feb 2019 15:44:24 +1100 Subject: [PATCH 1/5] Added starter files --- types/jsdoc-to-markdown/index.d.ts | 41 +++++++++++++++++++ .../jsdoc-to-markdown-tests.ts | 0 types/jsdoc-to-markdown/tsconfig.json | 25 +++++++++++ types/jsdoc-to-markdown/tslint.json | 3 ++ 4 files changed, 69 insertions(+) create mode 100644 types/jsdoc-to-markdown/index.d.ts create mode 100644 types/jsdoc-to-markdown/jsdoc-to-markdown-tests.ts create mode 100644 types/jsdoc-to-markdown/tsconfig.json create mode 100644 types/jsdoc-to-markdown/tslint.json diff --git a/types/jsdoc-to-markdown/index.d.ts b/types/jsdoc-to-markdown/index.d.ts new file mode 100644 index 0000000000..3cce87a6e6 --- /dev/null +++ b/types/jsdoc-to-markdown/index.d.ts @@ -0,0 +1,41 @@ +// Type definitions for jsdoc-to-markdown 4.0 +// Project: https://github.com/jsdoc2md/jsdoc-to-markdown +// Definitions by: Adam Zerella +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 2.9 + +interface RenderOptions { + data: object[]; + template?: string; + headingDepth?: number; + exampleLang?: string; + plugin?: string|string[]; + helper?: string|string[]; + partial?: string|string[]; + nameFormat?: string; + noGfm?: boolean; + seperators?: boolean; + moduleIndexFormat?: string; + globalIndexFormat?: string; // @todo + paramListFormat?: string; // @todo + propertyListFormat?: string; // @todo + memberIndexFormat?: string; // @todo +} + +interface JsdocOptions { + noCache: boolean; + files: string|string[]; + source: string; + configure: string; +} + +declare class JsdocToMarkdown { + render(options: RenderOptions): Promise; + renderSync(options: RenderOptions): string; + getTemplateData(options: JsdocOptions): object[]; + getTemplateDataSync(options: JsdocOptions): object[]; + getJsdocData(options: JsdocOptions): object[]; + getJsdocDataSync(options: JsdocOptions): object[]; + clear(): Promise; + getNamepaths(options: JsdocOptions): object; +} diff --git a/types/jsdoc-to-markdown/jsdoc-to-markdown-tests.ts b/types/jsdoc-to-markdown/jsdoc-to-markdown-tests.ts new file mode 100644 index 0000000000..e69de29bb2 diff --git a/types/jsdoc-to-markdown/tsconfig.json b/types/jsdoc-to-markdown/tsconfig.json new file mode 100644 index 0000000000..eabb42ab3b --- /dev/null +++ b/types/jsdoc-to-markdown/tsconfig.json @@ -0,0 +1,25 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": [ + "es6" + ], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "baseUrl": "../", + "typeRoots": [ + "../" + ], + "types": [ + + ], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "jsdoc-to-markdown-tests.ts" + ] +} diff --git a/types/jsdoc-to-markdown/tslint.json b/types/jsdoc-to-markdown/tslint.json new file mode 100644 index 0000000000..e60c15844f --- /dev/null +++ b/types/jsdoc-to-markdown/tslint.json @@ -0,0 +1,3 @@ +{ + "extends": "dtslint/dt.json" +} \ No newline at end of file From 0ba7d2203877b53c7f280032c1ad65c9424fd893 Mon Sep 17 00:00:00 2001 From: Adam Zerella Date: Thu, 14 Feb 2019 19:39:10 +1100 Subject: [PATCH 2/5] Added enum for format selections Updated async function return type --- types/jsdoc-to-markdown/index.d.ts | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/types/jsdoc-to-markdown/index.d.ts b/types/jsdoc-to-markdown/index.d.ts index 3cce87a6e6..ba3b34f781 100644 --- a/types/jsdoc-to-markdown/index.d.ts +++ b/types/jsdoc-to-markdown/index.d.ts @@ -4,6 +4,10 @@ // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.9 +declare enum StyleListFormat { "none", "grouped", "table", "dl" } +declare enum RenderListFormat { "list", "table" } +declare enum MemberIndexFormat { "grouped", "list" } + interface RenderOptions { data: object[]; template?: string; @@ -15,11 +19,11 @@ interface RenderOptions { nameFormat?: string; noGfm?: boolean; seperators?: boolean; - moduleIndexFormat?: string; - globalIndexFormat?: string; // @todo - paramListFormat?: string; // @todo - propertyListFormat?: string; // @todo - memberIndexFormat?: string; // @todo + moduleIndexFormat?: StyleListFormat; + globalIndexFormat?: StyleListFormat; + paramListFormat?: RenderListFormat; + propertyListFormat?: RenderListFormat; + memberIndexFormat?: MemberIndexFormat; } interface JsdocOptions { @@ -29,13 +33,13 @@ interface JsdocOptions { configure: string; } -declare class JsdocToMarkdown { +export default class JsdocToMarkdown { render(options: RenderOptions): Promise; renderSync(options: RenderOptions): string; - getTemplateData(options: JsdocOptions): object[]; + getTemplateData(options: JsdocOptions): Promise; getTemplateDataSync(options: JsdocOptions): object[]; - getJsdocData(options: JsdocOptions): object[]; + getJsdocData(options: JsdocOptions): Promise; getJsdocDataSync(options: JsdocOptions): object[]; clear(): Promise; - getNamepaths(options: JsdocOptions): object; + getNamepaths(options: JsdocOptions): Promise; } From ed257f8d6449b31309fb759d675e4117c869ca4a Mon Sep 17 00:00:00 2001 From: Adam Zerella Date: Thu, 14 Feb 2019 19:41:35 +1100 Subject: [PATCH 3/5] Added export for clarity --- types/jsdoc-to-markdown/index.d.ts | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/types/jsdoc-to-markdown/index.d.ts b/types/jsdoc-to-markdown/index.d.ts index ba3b34f781..d2fdbeda39 100644 --- a/types/jsdoc-to-markdown/index.d.ts +++ b/types/jsdoc-to-markdown/index.d.ts @@ -4,11 +4,11 @@ // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.9 -declare enum StyleListFormat { "none", "grouped", "table", "dl" } -declare enum RenderListFormat { "list", "table" } -declare enum MemberIndexFormat { "grouped", "list" } +export enum StyleListFormat { "none", "grouped", "table", "dl" } +export enum RenderListFormat { "list", "table" } +export enum MemberIndexFormat { "grouped", "list" } -interface RenderOptions { +export interface RenderOptions { data: object[]; template?: string; headingDepth?: number; @@ -26,14 +26,14 @@ interface RenderOptions { memberIndexFormat?: MemberIndexFormat; } -interface JsdocOptions { +export interface JsdocOptions { noCache: boolean; files: string|string[]; source: string; configure: string; } -export default class JsdocToMarkdown { +export class JsdocToMarkdown { render(options: RenderOptions): Promise; renderSync(options: RenderOptions): string; getTemplateData(options: JsdocOptions): Promise; From 07d65b09e1112fb683e3ff005da0024f6650f54c Mon Sep 17 00:00:00 2001 From: Adam Zerella Date: Thu, 14 Feb 2019 20:02:52 +1100 Subject: [PATCH 4/5] Added comments --- types/jsdoc-to-markdown/index.d.ts | 92 ++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/types/jsdoc-to-markdown/index.d.ts b/types/jsdoc-to-markdown/index.d.ts index d2fdbeda39..2c96a07f28 100644 --- a/types/jsdoc-to-markdown/index.d.ts +++ b/types/jsdoc-to-markdown/index.d.ts @@ -9,37 +9,129 @@ export enum RenderListFormat { "list", "table" } export enum MemberIndexFormat { "grouped", "list" } export interface RenderOptions { + /** + * Raw template data to use. Useful when you already have template data, obtained from .getTemplateData. + * Either files, source or data must be supplied. + */ data: object[]; + /** + * The template the supplied documentation will be rendered into. + * Use the default or supply your own template for full control over the output. + */ template?: string; + /** + * The initial heading depth. + * For example, with a value of 2 the top-level markdown headings look like "## The heading". + */ headingDepth?: number; + /** + * Specifies the default language used in '@example' blocks (for syntax-highlighting purposes). + * In gfm mode, each '@example' is wrapped in a fenced-code block. Example usage: --example-lang js. + * Use the special value none for no specific language. + * While using this option, you can override the supplied language + * for any '@example' by specifying the @lang subtag, + * e.g @example @lang hbs. Specifying @example @lang off will disable code blocks for that example. + */ exampleLang?: string; + /** + * Use an installed package containing helper and/or partial overrides. + */ plugin?: string|string[]; + /** + * handlebars helper files to override or extend the default set. + */ helper?: string|string[]; + /** + * handlebars partial files to override or extend the default set. + */ partial?: string|string[]; + /** + * Format identifier names in the code style, + * (i.e. format using backticks or ). + */ nameFormat?: string; + /** + * By default, dmd generates github-flavoured markdown. + * Not all markdown parsers render gfm correctly. + * If your generated docs look incorrect on sites other than Github + * (e.g. npmjs.org) try enabling this option to disable Github-specific syntax. + */ noGfm?: boolean; + /** + * Put
breaks between identifiers. Improves readability on bulky docs. + */ seperators?: boolean; moduleIndexFormat?: StyleListFormat; globalIndexFormat?: StyleListFormat; + /** + * Two options to render parameter lists: 'list' or 'table' (default). + * Table format works well in most cases but switch to list if things begin to look crowded / squashed. + */ paramListFormat?: RenderListFormat; propertyListFormat?: RenderListFormat; memberIndexFormat?: MemberIndexFormat; } export interface JsdocOptions { + /** + * By default results are cached to speed up repeat invocations. + * Set to true to disable this. + */ noCache: boolean; + /** + * One or more filenames to process. + * Accepts globs (e.g. *.js). Either files, source or data must be supplied. + */ files: string|string[]; + /** + * A string containing source code to process. + * Either files, source or data must be supplied. + */ source: string; + /** + * The path to the jsdoc configuration file. + * Default: path/to/jsdoc/conf.json. + */ configure: string; } export class JsdocToMarkdown { + /** + * Returns markdown documentation from jsdoc-annoted source code. + */ render(options: RenderOptions): Promise; + /** + * Sync version of render. + */ renderSync(options: RenderOptions): string; + /** + * Returns the template data (jsdoc-parse output) which is fed into the output template (dmd). + */ getTemplateData(options: JsdocOptions): Promise; + /** + * Sync version of getTemplateData. + */ getTemplateDataSync(options: JsdocOptions): object[]; + /** + * Returns raw data direct from the underlying jsdoc3. + */ getJsdocData(options: JsdocOptions): Promise; + /** + * Sync version of getJsdocData. + */ getJsdocDataSync(options: JsdocOptions): object[]; + /** + * By default, the output of each invocation of the main generation methods (render, getTemplateData etc) + * is stored in the cache (your system's temporary directory). + * Future jsdoc2md invocations with the same input options and source code will return the output immediately from cache, + * making the tool much faster/cheaper. If the input options or source code changes, + * fresh output will be generated. This method clears the cache, + * which you should never need to do unless the cache is failing for some reason. + * On Mac OSX, the system tmpdir clears itself every few days meaning your jsdoc2md cache will also be routinely cleared. + */ clear(): Promise; + /** + * Returns all jsdoc namepaths found in the supplied source code. + */ getNamepaths(options: JsdocOptions): Promise; } From f1b358066b10b8baa3cc9ccb042ed25397d1bb33 Mon Sep 17 00:00:00 2001 From: Adam Zerella Date: Thu, 14 Feb 2019 23:27:40 +1100 Subject: [PATCH 5/5] Moved everything into unified namespace Added basic function tests --- types/jsdoc-to-markdown/index.d.ts | 18 +++++++-------- .../jsdoc-to-markdown-tests.ts | 23 +++++++++++++++++++ 2 files changed, 32 insertions(+), 9 deletions(-) diff --git a/types/jsdoc-to-markdown/index.d.ts b/types/jsdoc-to-markdown/index.d.ts index 2c96a07f28..78b4d7d045 100644 --- a/types/jsdoc-to-markdown/index.d.ts +++ b/types/jsdoc-to-markdown/index.d.ts @@ -4,16 +4,16 @@ // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.9 -export enum StyleListFormat { "none", "grouped", "table", "dl" } -export enum RenderListFormat { "list", "table" } -export enum MemberIndexFormat { "grouped", "list" } +export type StyleListFormat = "none" | "grouped" | "table" | "dl"; +export type RenderListFormat = "list" | "table"; +export type MemberIndexFormat = "grouped" | "list"; export interface RenderOptions { /** * Raw template data to use. Useful when you already have template data, obtained from .getTemplateData. * Either files, source or data must be supplied. */ - data: object[]; + data?: object[]; /** * The template the supplied documentation will be rendered into. * Use the default or supply your own template for full control over the output. @@ -77,7 +77,7 @@ export interface JsdocOptions { * By default results are cached to speed up repeat invocations. * Set to true to disable this. */ - noCache: boolean; + noCache?: boolean; /** * One or more filenames to process. * Accepts globs (e.g. *.js). Either files, source or data must be supplied. @@ -87,23 +87,23 @@ export interface JsdocOptions { * A string containing source code to process. * Either files, source or data must be supplied. */ - source: string; + source?: string; /** * The path to the jsdoc configuration file. * Default: path/to/jsdoc/conf.json. */ - configure: string; + configure?: string; } export class JsdocToMarkdown { /** * Returns markdown documentation from jsdoc-annoted source code. */ - render(options: RenderOptions): Promise; + render(options: RenderOptions|JsdocOptions): Promise; /** * Sync version of render. */ - renderSync(options: RenderOptions): string; + renderSync(options: RenderOptions|JsdocOptions): string; /** * Returns the template data (jsdoc-parse output) which is fed into the output template (dmd). */ diff --git a/types/jsdoc-to-markdown/jsdoc-to-markdown-tests.ts b/types/jsdoc-to-markdown/jsdoc-to-markdown-tests.ts index e69de29bb2..e37d899bd4 100644 --- a/types/jsdoc-to-markdown/jsdoc-to-markdown-tests.ts +++ b/types/jsdoc-to-markdown/jsdoc-to-markdown-tests.ts @@ -0,0 +1,23 @@ +import { JsdocToMarkdown, StyleListFormat } from "jsdoc-to-markdown"; + +const jsdoc2md = new JsdocToMarkdown(); + +const JsdocDataOptions = { + files: "file.js" +}; + +const RenderOptions = { + data: [], + plugin: "", + helper: [""], + moduleIndexFormat: "table" as StyleListFormat +}; + +jsdoc2md.render(JsdocDataOptions); +jsdoc2md.renderSync(RenderOptions); +jsdoc2md.getTemplateData(JsdocDataOptions); +jsdoc2md.getTemplateDataSync(JsdocDataOptions); +jsdoc2md.getJsdocData(JsdocDataOptions); +jsdoc2md.getJsdocDataSync(JsdocDataOptions); +jsdoc2md.clear(); +jsdoc2md.getNamepaths(JsdocDataOptions);