Added comments

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 <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): Promise<string>;
+    /**
+     * 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<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>;
 }