Merge pull request #33064 from adamzerella/master

[jsdoc-to-markdown] Add jsdoc-to-markdown typing

types/jsdoc-to-markdown/index.d.ts

@@ -0,0 +1,137 @@
+// 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;
+}
+
+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>;
+}

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

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

types/jsdoc-to-markdown/tslint.json

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