0
# Programmatic API
1

2
Core programmatic interface for generating markdown documentation from JSDoc-annotated source code. The API is provided through a singleton instance exported as the default export.
3

4
## Capabilities
5

6
### Render Method
7

8
Generates markdown documentation from JSDoc-annotated source code with comprehensive customization options.
9

10
```javascript { .api }
11
/**
12
 * Returns markdown documentation from jsdoc-annotated source code
13
 * @param {RenderOptions} [options={}] - Configuration options
14
 * @returns {Promise<string>} The rendered markdown documentation
15
 */
16
async function render(options = {});
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
import jsdoc2md from 'jsdoc-to-markdown';
23

24
// Basic file processing
25
const docs = await jsdoc2md.render({ files: 'lib/*.js' });
26

27
// Process source code directly
28
const docs = await jsdoc2md.render({
29
  source: `
30
    /**
31
     * Adds two numbers together.
32
     * @param {number} a - First number
33
     * @param {number} b - Second number
34
     * @returns {number} Sum of a and b
35
     */
36
    function add(a, b) {
37
      return a + b;
38
    }
39
  `
40
});
41

42
// Custom template and formatting
43
const docs = await jsdoc2md.render({
44
  files: 'src/*.js',
45
  template: '{{>main}}',
46
  'heading-depth': 1,
47
  'example-lang': 'javascript',
48
  separators: true
49
});
50

51
// Use pre-fetched template data
52
const templateData = await jsdoc2md.getTemplateData({ files: 'src/*.js' });
53
const docs = await jsdoc2md.render({ data: templateData });
54
```
55

56
### Get Template Data Method
57

58
Returns the template data (jsdoc-parse output) which is fed into the output template engine.
59

60
```javascript { .api }
61
/**
62
 * Returns the template data (jsdoc-parse output) which is fed into the output template
63
 * @param {TemplateDataOptions} [options={}] - Configuration options
64
 * @returns {Promise<object[]>} The parsed template data
65
 */
66
async function getTemplateData(options = {});
67
```
68

69
**Usage Examples:**
70

71
```javascript
72
import jsdoc2md from 'jsdoc-to-markdown';
73

74
// Get processed template data
75
const templateData = await jsdoc2md.getTemplateData({
76
  files: ['lib/module-a.js', 'lib/module-b.js']
77
});
78

79
// Use with custom processing
80
const templateData = await jsdoc2md.getTemplateData({ files: 'src/*.js' });
81
// Filter or modify templateData as needed
82
const filteredData = templateData.filter(item => !item.ignore);
83
const docs = await jsdoc2md.render({ data: filteredData });
84
```
85

86
### Get JSDoc Data Method
87

88
Returns raw data direct from the underlying JSDoc parser, before any processing or transformation.
89

90
```javascript { .api }
91
/**
92
 * Returns raw data direct from the underlying jsdoc3
93
 * @param {JsdocDataOptions} options - Configuration options (required)
94
 * @returns {Promise<object[]>} Raw JSDoc data
95
 */
96
async function getJsdocData(options);
97
```
98

99
**Usage Examples:**
100

101
```javascript
102
import jsdoc2md from 'jsdoc-to-markdown';
103

104
// Get raw JSDoc data
105
const rawData = await jsdoc2md.getJsdocData({
106
  files: 'src/**/*.js'
107
});
108

109
// Process with custom JSDoc configuration
110
const rawData = await jsdoc2md.getJsdocData({
111
  configure: './jsdoc.conf.json'
112
});
113

114
// Disable caching for development
115
const rawData = await jsdoc2md.getJsdocData({
116
  files: 'src/*.js',
117
  'no-cache': true
118
});
119
```
120

121
### Clear Cache Method
122

123
Clears the internal cache used for performance optimization. Cache is stored in the system's temporary directory and is automatically managed, but this method allows manual clearing when needed.
124

125
```javascript { .api }
126
/**
127
 * Clears the cache stored in the system's temporary directory
128
 * @returns {Promise<void>}
129
 */
130
async function clear();
131
```
132

133
**Usage Examples:**
134

135
```javascript
136
import jsdoc2md from 'jsdoc-to-markdown';
137

138
// Clear cache before processing
139
await jsdoc2md.clear();
140

141
// Clear cache for troubleshooting
142
try {
143
  const docs = await jsdoc2md.render({ files: 'src/*.js' });
144
} catch (error) {
145
  // Clear cache and retry
146
  await jsdoc2md.clear();
147
  const docs = await jsdoc2md.render({ files: 'src/*.js' });
148
}
149
```
150

151
### Get Namepaths Method
152

153
Returns all JSDoc namepaths found in the supplied source code, organized by identifier kind.
154

155
```javascript { .api }
156
/**
157
 * Returns all jsdoc namepaths found in the supplied source code
158
 * @param {NamepathOptions} options - Configuration options
159
 * @returns {Promise<object>} Namepaths organized by kind
160
 */
161
async function getNamepaths(options);
162
```
163

164
**Usage Examples:**
165

166
```javascript
167
import jsdoc2md from 'jsdoc-to-markdown';
168

169
// Get all namepaths
170
const namepaths = await jsdoc2md.getNamepaths({
171
  files: 'src/*.js'
172
});
173

174
/* Returns object like:
175
{
176
  "module": ["module:utils", "module:helpers"],
177
  "class": ["MyClass", "DataProcessor"],
178
  "function": ["processData", "formatOutput"],
179
  "constant": ["DEFAULT_CONFIG", "VERSION"],
180
  "member": ["MyClass.prototype.value"],
181
  "namespace": ["Utils"],
182
  "constructor": ["MyClass"],
183
  "mixin": ["EventMixin"],
184
  "event": ["data:loaded"],
185
  "typedef": ["DataConfig", "ProcessResult"],
186
  "external": ["jQuery", "lodash"]
187
}
188
*/
189

190
// Use for documentation analysis
191
const namepaths = await jsdoc2md.getNamepaths({ files: 'lib/*.js' });
192
const functionCount = namepaths.function.length;
193
const classCount = namepaths.class.length;
194
console.log(`Found ${functionCount} functions and ${classCount} classes`);
195
```
196

197
## Configuration Options
198

199
### RenderOptions
200

201
Complete configuration interface for the render method, extending all template data and JSDoc options.
202

203
```javascript { .api }
204
interface RenderOptions extends TemplateDataOptions {
205
  /** Raw template data to use instead of parsing files */
206
  data?: object[];
207
  /** Custom handlebars template for full control over output */
208
  template?: string;
209
  /** Initial heading depth (default: 2) */
210
  'heading-depth'?: number;
211
  /** Default language for @example blocks */
212
  'example-lang'?: string;
213
  /** Installed package containing helper/partial overrides */
214
  plugin?: string | string[];
215
  /** Handlebars helper files to override defaults */
216
  helper?: string | string[];
217
  /** Handlebars partial files to override defaults */
218
  partial?: string | string[];
219
  /** Format identifier names as code (wrap in backticks) */
220
  'name-format'?: boolean;
221
  /** Disable GitHub-flavored markdown */
222
  'no-gfm'?: boolean;
223
  /** Add horizontal rule breaks between identifiers */
224
  separators?: boolean;
225
  /** Module index format: none, grouped, table, dl */
226
  'module-index-format'?: string;
227
  /** Global index format: none, grouped, table, dl */
228
  'global-index-format'?: string;
229
  /** Parameter list format: list, table */
230
  'param-list-format'?: string;
231
  /** Property list format: list, table */
232
  'property-list-format'?: string;
233
  /** Member index format: grouped, list */
234
  'member-index-format'?: string;
235
  /** Render URL links in plain text, others in monospace */
236
  'clever-links'?: boolean;
237
  /** Render all links in monospace */
238
  'monospace-links'?: boolean;
239
  /** EOL character: posix, win32 */
240
  EOL?: string;
241
}
242
```
243

244
### TemplateDataOptions
245

246
Options for getting template data, identical to JSDoc data options.
247

248
```javascript { .api }
249
interface TemplateDataOptions extends JsdocDataOptions {}
250
```
251

252
### JsdocDataOptions
253

254
Core options for JSDoc data processing.
255

256
```javascript { .api }
257
interface JsdocDataOptions {
258
  /** Disable caching for this invocation */
259
  'no-cache'?: boolean;
260
  /** File paths or glob patterns to process */
261
  files?: string | string[];
262
  /** Source code string to process */
263
  source?: string;
264
  /** Path to JSDoc configuration file */
265
  configure?: string;
266
}
267
```
268

269
### NamepathOptions
270

271
Options for namepath extraction, identical to template data options.
272

273
```javascript { .api }
274
interface NamepathOptions extends TemplateDataOptions {}
275
```
276

277
## Error Handling
278

279
All methods are async and may throw errors. Common error scenarios include:
280

281
- **File not found**: When specified files don't exist
282
- **Invalid JSDoc**: When source code contains malformed JSDoc comments
283
- **Template errors**: When custom templates have syntax errors
284
- **Configuration errors**: When JSDoc configuration files are invalid
285

286
```javascript
287
import jsdoc2md from 'jsdoc-to-markdown';
288

289
try {
290
  const docs = await jsdoc2md.render({ files: 'src/*.js' });
291
} catch (error) {
292
  if (error.message.includes('ENOENT')) {
293
    console.error('Files not found');
294
  } else if (error.message.includes('jsdoc')) {
295
    console.error('JSDoc parsing error:', error.message);
296
  } else {
297
    console.error('Unexpected error:', error);
298
  }
299
}
300
```