1 | // Type definitions for jsdoc-to-markdown 7.0
|
2 | // Project: https://github.com/jsdoc2md/jsdoc-to-markdown
|
3 | // Definitions by: Piotr Błażejewicz <https://github.com/peterblazejewicz>
|
4 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
5 |
|
6 | export type StyleListFormat = 'none' | 'grouped' | 'table' | 'dl';
|
7 | export type RenderListFormat = 'list' | 'table';
|
8 | export type MemberIndexFormat = 'grouped' | 'list';
|
9 |
|
10 | export interface RenderOptions {
|
11 | /**
|
12 | * Raw template data to use. Useful when you already have template data, obtained from .getTemplateData.
|
13 | * Either files, source or data must be supplied.
|
14 | */
|
15 | data?: object[] | undefined;
|
16 | /**
|
17 | * The template the supplied documentation will be rendered into.
|
18 | * Use the default or supply your own template for full control over the output.
|
19 | */
|
20 | template?: string | undefined;
|
21 | /**
|
22 | * The initial heading depth.
|
23 | * For example, with a value of 2 the top-level markdown headings look like "## The heading".
|
24 | */
|
25 | 'heading-depth'?: number | undefined;
|
26 | /**
|
27 | * Specifies the default language used in '@example' blocks (for syntax-highlighting purposes).
|
28 | * In gfm mode, each '@example' is wrapped in a fenced-code block. Example usage: --example-lang js.
|
29 | * Use the special value none for no specific language.
|
30 | * While using this option, you can override the supplied language
|
31 | * for any '@example' by specifying the @lang subtag,
|
32 | * e.g @example @lang hbs. Specifying @example @lang off will disable code blocks for that example.
|
33 | */
|
34 | 'example-lang'?: string | undefined;
|
35 | /**
|
36 | * Use an installed package containing helper and/or partial overrides.
|
37 | */
|
38 | plugin?: string | string[] | undefined;
|
39 | /**
|
40 | * handlebars helper files to override or extend the default set.
|
41 | */
|
42 | helper?: string | string[] | undefined;
|
43 | /**
|
44 | * handlebars partial files to override or extend the default set.
|
45 | */
|
46 | partial?: string | string[] | undefined;
|
47 | /**
|
48 | * Format identifier names in the code style,
|
49 | * (i.e. format using backticks or <code></code>).
|
50 | */
|
51 | 'name-format'?: string | undefined;
|
52 | /**
|
53 | * By default, dmd generates github-flavoured markdown.
|
54 | * Not all markdown parsers render gfm correctly.
|
55 | * If your generated docs look incorrect on sites other than Github
|
56 | * (e.g. npmjs.org) try enabling this option to disable Github-specific syntax.
|
57 | */
|
58 | 'no-gfm'?: boolean | undefined;
|
59 | /**
|
60 | * Put <hr> breaks between identifiers. Improves readability on bulky docs.
|
61 | */
|
62 | separators?: boolean | undefined;
|
63 | 'module-index-format'?: StyleListFormat | undefined;
|
64 | 'global-index-format'?: StyleListFormat | undefined;
|
65 | /**
|
66 | * Two options to render parameter lists: 'list' or 'table' (default).
|
67 | * Table format works well in most cases but switch to list if things begin to look crowded / squashed.
|
68 | */
|
69 | 'param-list-format'?: RenderListFormat | undefined;
|
70 | 'property-list-format'?: RenderListFormat | undefined;
|
71 | 'member-index-format'?: MemberIndexFormat | undefined;
|
72 | }
|
73 |
|
74 | export interface JsdocOptions {
|
75 | /**
|
76 | * By default results are cached to speed up repeat invocations.
|
77 | * Set to true to disable this.
|
78 | */
|
79 | 'no-cache'?: boolean | undefined;
|
80 | /**
|
81 | * One or more filenames to process.
|
82 | * Accepts globs (e.g. *.js). Either files, source or data must be supplied.
|
83 | */
|
84 | files: string | string[];
|
85 | /**
|
86 | * A string containing source code to process.
|
87 | * Either files, source or data must be supplied.
|
88 | */
|
89 | source?: string | undefined;
|
90 | /**
|
91 | * The path to the jsdoc configuration file.
|
92 | * Default: path/to/jsdoc/conf.json.
|
93 | */
|
94 | configure?: string | undefined;
|
95 | }
|
96 |
|
97 | /**
|
98 | * Returns markdown documentation from jsdoc-annotated source code.
|
99 | */
|
100 | export function render(options: RenderOptions | JsdocOptions): Promise<string>;
|
101 |
|
102 | /**
|
103 | * Sync version of render.
|
104 | */
|
105 | export function renderSync(options: RenderOptions | JsdocOptions): string;
|
106 |
|
107 | /**
|
108 | * Returns the template data (jsdoc-parse output) which is fed into the output template (dmd).
|
109 | */
|
110 | export function getTemplateData(options: JsdocOptions): Promise<object[]>;
|
111 |
|
112 | /**
|
113 | * Sync version of getTemplateData.
|
114 | */
|
115 | export function getTemplateDataSync(options: JsdocOptions): object[];
|
116 |
|
117 | /**
|
118 | * Returns raw data direct from the underlying jsdoc3.
|
119 | */
|
120 | export function getJsdocData(options: JsdocOptions): Promise<object[]>;
|
121 |
|
122 | /**
|
123 | * Sync version of getJsdocData.
|
124 | */
|
125 | export function getJsdocDataSync(options: JsdocOptions): object[];
|
126 |
|
127 | /**
|
128 | * By default, the output of each invocation of the main generation methods (render, getTemplateData etc)
|
129 | * is stored in the cache (your system's temporary directory).
|
130 | * Future jsdoc2md invocations with the same input options and source code will return the output immediately from cache,
|
131 | * making the tool much faster/cheaper. If the input options or source code changes,
|
132 | * fresh output will be generated. This method clears the cache,
|
133 | * which you should never need to do unless the cache is failing for some reason.
|
134 | * On Mac OSX, the system tmpdir clears itself every few days meaning your jsdoc2md cache will also be routinely cleared.
|
135 | */
|
136 | export function clear(): Promise<void>;
|
137 |
|
138 | /**
|
139 | * Returns all jsdoc namepaths found in the supplied source code.
|
140 | */
|
141 | export function getNamepaths(options: JsdocOptions): Promise<object>;
|