// 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>;
}