fix(jsdoc-to-markdown): correct module definition and update to v5 (#42732)

* 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

@@ -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 <https://github.com/adamzerella>
+//                  Piotr Błażejewicz <https://github.com/peterblazejewicz>
 // 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 <code></code>).
@@ -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<string>;
-    /**
-     * 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<object[]>;
-    /**
-     * Sync version of getTemplateData.
-     */
-    getTemplateDataSync(options: JsdocOptions): object[];
-    /**
-     * Returns raw data direct from the underlying jsdoc3.
-     */
-    getJsdocData(options: JsdocOptions): Promise<object[]>;
-    /**
-     * 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<void>;
-    /**
-     * Returns all jsdoc namepaths found in the supplied source code.
-     */
-    getNamepaths(options: JsdocOptions): Promise<object>;
-}
+/**
+ * Returns markdown documentation from jsdoc-annoted source code.
+ */
+export function render(options: RenderOptions | JsdocOptions): Promise<string>;
+
+/**
+ * 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<object[]>;
+
+/**
+ * Sync version of getTemplateData.
+ */
+export function getTemplateDataSync(options: JsdocOptions): object[];
+
+/**
+ * Returns raw data direct from the underlying jsdoc3.
+ */
+export function getJsdocData(options: JsdocOptions): Promise<object[]>;
+
+/**
+ * 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<void>;
+
+/**
+ * Returns all jsdoc namepaths found in the supplied source code.
+ */
+export function getNamepaths(options: JsdocOptions): Promise<object>;

types/jsdoc-to-markdown/jsdoc-to-markdown-tests.ts

@@ -1,23 +1,35 @@
-import { JsdocToMarkdown, StyleListFormat } from "jsdoc-to-markdown";
+/// <reference types="node" />
+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<string>
+jsdoc2md.renderSync(RenderOptions); // $ExpectType string
+jsdoc2md.getTemplateData(JsdocDataOptions); // $ExpectType Promise<object[]>
+jsdoc2md.getTemplateDataSync(JsdocDataOptions); // $ExpectType object[]
+jsdoc2md.getJsdocData(JsdocDataOptions); // $ExpectType Promise<object[]>
+jsdoc2md.getJsdocDataSync(JsdocDataOptions); // $ExpectType object[]
+jsdoc2md.clear(); // $ExpectType Promise<void>
+jsdoc2md.getNamepaths(JsdocDataOptions); // $ExpectType Promise<object>
+
+(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
+})();

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 <https://github.com/adamzerella>
+// 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 <code></code>).
+     */
+    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 <hr> 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<string>;
+/**
+ * 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<object[]>;
+/**
+ * Sync version of getTemplateData.
+ */
+export function getTemplateDataSync(options: JsdocOptions): object[];
+/**
+ * Returns raw data direct from the underlying jsdoc3.
+ */
+export function getJsdocData(options: JsdocOptions): Promise<object[]>;
+/**
+ * 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<void>;
+/**
+ * Returns all jsdoc namepaths found in the supplied source code.
+ */
+export function getNamepaths(options: JsdocOptions): Promise<object>;

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);

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"
+    ]
+}

types/jsdoc-to-markdown/v4/tslint.json

@@ -0,0 +1,3 @@
+{
+    "extends": "dtslint/dt.json"
+}