From f32c44b81f1fd0f657fc39b43629f26b580ddef4 Mon Sep 17 00:00:00 2001 From: Andrew Casey Date: Wed, 4 Mar 2020 16:13:58 -0800 Subject: [PATCH] fix(jsdoc-to-markdown): correct module definition and update to v5 (#42732) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(jsdoc-to-markdown): correct module definition and update to v5 - update module definition fixing errors like: ```bash TSError: ⨯ Unable to compile TypeScript: index.ts:3:10 - error TS2339: Property 'render' does not exist on type 'typeof import("../node_modules/@types/jsdoc-to-markdown/index")'. 3 jsdoc2md.render({ files: 'src/*.js' }).then(...) ``` After this change the module is exported as regular CommonJS module - update version to v5 - create backward compatible v4 - rewrite tests to match CommonJS module exports https://github.com/jsdoc2md/jsdoc-to-markdown/blob/master/docs/API.md#jsdoc-to-markdown Thanks! * Fix v4 module definition as per PR comment - module exports correct also for v4 - tests corrected for v4 /cc @amcasey --- types/jsdoc-to-markdown/index.d.ts | 103 ++++++------- .../jsdoc-to-markdown-tests.ts | 42 ++++-- types/jsdoc-to-markdown/v4/index.d.ts | 135 ++++++++++++++++++ .../v4/jsdoc-to-markdown-tests.ts | 22 +++ types/jsdoc-to-markdown/v4/tsconfig.json | 30 ++++ types/jsdoc-to-markdown/v4/tslint.json | 3 + 6 files changed, 271 insertions(+), 64 deletions(-) create mode 100644 types/jsdoc-to-markdown/v4/index.d.ts create mode 100644 types/jsdoc-to-markdown/v4/jsdoc-to-markdown-tests.ts create mode 100644 types/jsdoc-to-markdown/v4/tsconfig.json create mode 100644 types/jsdoc-to-markdown/v4/tslint.json diff --git a/types/jsdoc-to-markdown/index.d.ts b/types/jsdoc-to-markdown/index.d.ts index 78b4d7d045..9a8a9be051 100644 --- a/types/jsdoc-to-markdown/index.d.ts +++ b/types/jsdoc-to-markdown/index.d.ts @@ -1,12 +1,12 @@ -// Type definitions for jsdoc-to-markdown 4.0 +// Type definitions for jsdoc-to-markdown 5.0 // Project: https://github.com/jsdoc2md/jsdoc-to-markdown // Definitions by: Adam Zerella +// Piotr Błażejewicz // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped -// TypeScript Version: 2.9 -export type StyleListFormat = "none" | "grouped" | "table" | "dl"; -export type RenderListFormat = "list" | "table"; -export type MemberIndexFormat = "grouped" | "list"; +export type StyleListFormat = 'none' | 'grouped' | 'table' | 'dl'; +export type RenderListFormat = 'list' | 'table'; +export type MemberIndexFormat = 'grouped' | 'list'; export interface RenderOptions { /** @@ -36,15 +36,15 @@ export interface RenderOptions { /** * Use an installed package containing helper and/or partial overrides. */ - plugin?: string|string[]; + plugin?: string | string[]; /** * handlebars helper files to override or extend the default set. */ - helper?: string|string[]; + helper?: string | string[]; /** * handlebars partial files to override or extend the default set. */ - partial?: string|string[]; + partial?: string | string[]; /** * Format identifier names in the code style, * (i.e. format using backticks or ). @@ -82,7 +82,7 @@ export interface JsdocOptions { * One or more filenames to process. * Accepts globs (e.g. *.js). Either files, source or data must be supplied. */ - files: string|string[]; + files: string | string[]; /** * A string containing source code to process. * Either files, source or data must be supplied. @@ -95,43 +95,48 @@ export interface JsdocOptions { configure?: string; } -export class JsdocToMarkdown { - /** - * Returns markdown documentation from jsdoc-annoted source code. - */ - render(options: RenderOptions|JsdocOptions): Promise; - /** - * Sync version of render. - */ - renderSync(options: RenderOptions|JsdocOptions): 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; -} +/** + * Returns markdown documentation from jsdoc-annoted source code. + */ +export function render(options: RenderOptions | JsdocOptions): Promise; + +/** + * Sync version of render. + */ +export function renderSync(options: RenderOptions | JsdocOptions): string; + +/** + * Returns the template data (jsdoc-parse output) which is fed into the output template (dmd). + */ +export function getTemplateData(options: JsdocOptions): Promise; + +/** + * Sync version of getTemplateData. + */ +export function getTemplateDataSync(options: JsdocOptions): object[]; + +/** + * Returns raw data direct from the underlying jsdoc3. + */ +export function getJsdocData(options: JsdocOptions): Promise; + +/** + * Sync version of getJsdocData. + */ +export function 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. + */ +export function clear(): Promise; + +/** + * Returns all jsdoc namepaths found in the supplied source code. + */ +export function getNamepaths(options: JsdocOptions): Promise; diff --git a/types/jsdoc-to-markdown/jsdoc-to-markdown-tests.ts b/types/jsdoc-to-markdown/jsdoc-to-markdown-tests.ts index e37d899bd4..744e50317c 100644 --- a/types/jsdoc-to-markdown/jsdoc-to-markdown-tests.ts +++ b/types/jsdoc-to-markdown/jsdoc-to-markdown-tests.ts @@ -1,23 +1,35 @@ -import { JsdocToMarkdown, StyleListFormat } from "jsdoc-to-markdown"; +/// +import jsdoc2md = require('jsdoc-to-markdown'); +import fs = require('fs'); -const jsdoc2md = new JsdocToMarkdown(); +const output = jsdoc2md.renderSync({ files: 'lib/*.js' }); + +fs.writeFileSync('api.md', output); const JsdocDataOptions = { - files: "file.js" + files: 'file.js', }; -const RenderOptions = { +const RenderOptions: jsdoc2md.RenderOptions = { data: [], - plugin: "", - helper: [""], - moduleIndexFormat: "table" as StyleListFormat + plugin: '', + helper: [''], + moduleIndexFormat: 'table', }; -jsdoc2md.render(JsdocDataOptions); -jsdoc2md.renderSync(RenderOptions); -jsdoc2md.getTemplateData(JsdocDataOptions); -jsdoc2md.getTemplateDataSync(JsdocDataOptions); -jsdoc2md.getJsdocData(JsdocDataOptions); -jsdoc2md.getJsdocDataSync(JsdocDataOptions); -jsdoc2md.clear(); -jsdoc2md.getNamepaths(JsdocDataOptions); +jsdoc2md.render(JsdocDataOptions); // $ExpectType Promise +jsdoc2md.renderSync(RenderOptions); // $ExpectType string +jsdoc2md.getTemplateData(JsdocDataOptions); // $ExpectType Promise +jsdoc2md.getTemplateDataSync(JsdocDataOptions); // $ExpectType object[] +jsdoc2md.getJsdocData(JsdocDataOptions); // $ExpectType Promise +jsdoc2md.getJsdocDataSync(JsdocDataOptions); // $ExpectType object[] +jsdoc2md.clear(); // $ExpectType Promise +jsdoc2md.getNamepaths(JsdocDataOptions); // $ExpectType Promise + +(async () => { + await jsdoc2md.render(JsdocDataOptions); // $ExpectType string + await jsdoc2md.getTemplateData(JsdocDataOptions); // $ExpectType object[] + await jsdoc2md.getJsdocData(JsdocDataOptions); // $ExpectType object[] + await jsdoc2md.clear(); // $ExpectType void + await jsdoc2md.getNamepaths(JsdocDataOptions); // $ExpectType object +})(); diff --git a/types/jsdoc-to-markdown/v4/index.d.ts b/types/jsdoc-to-markdown/v4/index.d.ts new file mode 100644 index 0000000000..4116b16ea5 --- /dev/null +++ b/types/jsdoc-to-markdown/v4/index.d.ts @@ -0,0 +1,135 @@ +// 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 + +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[]; + /** + * 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; +} + +/** + * Returns markdown documentation from jsdoc-annoted source code. + */ +export function render(options: RenderOptions | JsdocOptions): Promise; +/** + * Sync version of render. + */ +export function renderSync(options: RenderOptions | JsdocOptions): string; +/** + * Returns the template data (jsdoc-parse output) which is fed into the output template (dmd). + */ +export function getTemplateData(options: JsdocOptions): Promise; +/** + * Sync version of getTemplateData. + */ +export function getTemplateDataSync(options: JsdocOptions): object[]; +/** + * Returns raw data direct from the underlying jsdoc3. + */ +export function getJsdocData(options: JsdocOptions): Promise; +/** + * Sync version of getJsdocData. + */ +export function 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. + */ +export function clear(): Promise; +/** + * Returns all jsdoc namepaths found in the supplied source code. + */ +export function getNamepaths(options: JsdocOptions): Promise; diff --git a/types/jsdoc-to-markdown/v4/jsdoc-to-markdown-tests.ts b/types/jsdoc-to-markdown/v4/jsdoc-to-markdown-tests.ts new file mode 100644 index 0000000000..8e7e31b04b --- /dev/null +++ b/types/jsdoc-to-markdown/v4/jsdoc-to-markdown-tests.ts @@ -0,0 +1,22 @@ +import jsdoc2md = require('jsdoc-to-markdown'); +import { StyleListFormat } from 'jsdoc-to-markdown'; + +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); diff --git a/types/jsdoc-to-markdown/v4/tsconfig.json b/types/jsdoc-to-markdown/v4/tsconfig.json new file mode 100644 index 0000000000..f27952120f --- /dev/null +++ b/types/jsdoc-to-markdown/v4/tsconfig.json @@ -0,0 +1,30 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": [ + "es6" + ], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "baseUrl": "../../", + "typeRoots": [ + "../../" + ], + "types": [ + + ], + "paths": { + "jsdoc-to-markdown": [ + "jsdoc-to-markdown/v4" + ] + }, + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "jsdoc-to-markdown-tests.ts" + ] +} diff --git a/types/jsdoc-to-markdown/v4/tslint.json b/types/jsdoc-to-markdown/v4/tslint.json new file mode 100644 index 0000000000..e60c15844f --- /dev/null +++ b/types/jsdoc-to-markdown/v4/tslint.json @@ -0,0 +1,3 @@ +{ + "extends": "dtslint/dt.json" +} \ No newline at end of file