0
# JSDoc
1

2
JSDoc is a comprehensive API documentation generator for JavaScript that parses source code and JSDoc comments to produce HTML documentation. It supports modern JavaScript features through Babel parser integration, provides flexible templating systems for customizing documentation output, and includes extensive plugin architecture for extending functionality.
3

4
## Package Information
5

6
- **Package Name**: jsdoc
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install -g jsdoc` or `npm install --save-dev jsdoc`
10

11
## Core Imports
12

13
JSDoc provides a custom require system that allows importing from the `lib/jsdoc/` directory using the `jsdoc/` prefix:
14

15
```javascript
16
// Environment and configuration
17
const env = require('jsdoc/env');
18
const Config = require('jsdoc/config');
19

20
// Parser and AST processing
21
const parser = require('jsdoc/src/parser');
22
const astnode = require('jsdoc/src/astnode');
23
const syntax = require('jsdoc/src/syntax');
24

25
// Doclet processing
26
const doclet = require('jsdoc/doclet');
27
const name = require('jsdoc/name');
28

29
// Utilities
30
const logger = require('jsdoc/util/logger');
31
const templateHelper = require('jsdoc/util/templateHelper');
32
```
33

34
The custom require system is set up by the main `jsdoc.js` entry point and allows access to all internal modules.
35

36
## Basic Usage
37

38
### Command Line Usage
39

40
```bash
41
# Generate documentation for a single file
42
jsdoc myfile.js
43

44
# Generate documentation with configuration
45
jsdoc -c conf.json src/**/*.js
46

47
# Generate documentation with custom template
48
jsdoc -t templates/custom src/**/*.js -d output/
49
```
50

51
### Programmatic Usage
52

53
```javascript
54
const parser = require('jsdoc/src/parser');
55
const env = require('jsdoc/env');
56

57
// Set up environment
58
env.opts = { encoding: 'utf8' };
59
env.conf = { source: { includePattern: '\\.js$' } };
60

61
// Create parser and parse files
62
const jsdocParser = parser.createParser();
63
const doclets = jsdocParser.parse(['myfile.js']);
64

65
console.log('Generated', doclets.length, 'doclets');
66
```
67

68
## Architecture
69

70
JSDoc is built around several key components:
71

72
- **Command-Line Interface**: Primary user interface with extensive configuration options
73
- **Parser Engine**: JavaScript AST parsing with JSDoc comment extraction and doclet generation
74
- **Plugin System**: Extensible architecture for custom tags, handlers, and processing
75
- **Template System**: Flexible HTML generation with customizable themes and layouts
76
- **Configuration System**: JSON-based configuration with environment and CLI option support
77

78
## Capabilities
79

80
### Command-Line Interface
81

82
Complete command-line tool for generating documentation from JavaScript source files. Supports recursive directory scanning, flexible configuration, and multiple output formats.
83

84
```bash
85
# Primary command interface
86
jsdoc [options] <source files>
87

88
# Examples
89
jsdoc src/**/*.js --destination docs/
90
jsdoc -c jsdoc.conf.json src/
91
jsdoc --help
92
```
93

94
**Note**: The CLI module is internal and not designed for programmatic use. For programmatic access, use the core modules directly.
95

96
[Command-Line Interface](./cli.md)
97

98
### JavaScript Parser
99

100
Core parsing engine that analyzes JavaScript source code, extracts JSDoc comments, and generates documentation objects (doclets). Supports modern ES6+ syntax and provides event-driven processing.
101

102
```javascript { .api }
103
const parser = {
104
  createParser(type?: string): Parser;
105
  PARSERS: { js: string };
106
}
107

108
class Parser {
109
  constructor(builderInstance?, visitorInstance?, walkerInstance?);
110
  parse(sourceFiles: string[], encoding?: string): Doclet[];
111
  addResult(doclet: Doclet): void;
112
  addAstNodeVisitor(visitor: Function): void;
113
  clear(): void;
114
}
115
```
116

117
[JavaScript Parser](./parser.md)
118

119
### Plugin System
120

121
Extensible plugin architecture allowing custom JSDoc tags, event handlers, and AST node visitors. Includes built-in plugins for common tasks like Markdown processing and template customization.
122

123
```javascript { .api }
124
const plugins = {
125
  installPlugins(plugins: string[], parser: Parser): void;
126
}
127

128
// Plugin interface
129
interface Plugin {
130
  handlers?: { [eventName: string]: Function };
131
  defineTags?(dictionary: TagDictionary): void;
132
  astNodeVisitor?: Function;
133
}
134
```
135

136
[Plugin System](./plugins.md)
137

138
### Template System
139

140
Flexible template engine for generating HTML documentation. Supports custom templates, layouts, and helper functions with complete control over output formatting.
141

142
```javascript { .api }
143
class Template {
144
  constructor(filepath: string);
145
  load(file: string): Function;
146
  partial(file: string, data: object): string;
147
  render(file: string, data: object): string;
148
}
149

150
// Template publish function interface
151
function publish(data: TaffyDB, opts: object): void;
152
```
153

154
[Template System](./templates.md)
155

156
### Configuration Management
157

158
JSON-based configuration system with support for source patterns, plugin loading, template selection, and output customization.
159

160
```javascript { .api }
161
class Config {
162
  constructor(jsonOrObject?: string | object);
163
  get(): ConfigObject;
164
}
165

166
interface ConfigObject {
167
  plugins: string[];
168
  recurseDepth: number;
169
  source: {
170
    includePattern: string;
171
    excludePattern: string;
172
  };
173
  sourceType: string;
174
  tags: {
175
    allowUnknownTags: boolean;
176
    dictionaries: string[];
177
  };
178
  templates: {
179
    monospaceLinks: boolean;
180
    cleverLinks: boolean;
181
  };
182
}
183
```
184

185
[Configuration](./configuration.md)
186

187
### Environment and Runtime
188

189
Environment management providing access to command-line options, configuration data, version information, and runtime state.
190

191
```javascript { .api }
192
const env = {
193
  run: { start: Date; finish: Date | null };
194
  args: any[];
195
  conf: object;
196
  dirname: string;
197
  pwd: string;
198
  opts: object;
199
  sourceFiles: string[];
200
  version: { number: string; revision: string };
201
}
202
```
203

204
[Environment and Runtime](./environment.md)
205

206
### Utilities
207

208
Comprehensive utility modules for logging, data manipulation, debugging, template helpers, and common operations used throughout JSDoc.
209

210
```javascript { .api }
211
// Logging system
212
const logger = {
213
  LEVELS: { TRACE: 10; DEBUG: 20; INFO: 30; WARN: 40; ERROR: 50; FATAL: 60; };
214
  setLevel(level: number | string): void;
215
  trace(message: string, ...args: any[]): void;
216
  debug(message: string, ...args: any[]): void;
217
  info(message: string, ...args: any[]): void;
218
  warn(message: string, ...args: any[]): void;
219
  error(message: string, ...args: any[]): void;
220
  fatal(message: string, ...args: any[]): void;
221
}
222

223
// Template helpers
224
const templateHelper = {
225
  longnameToUrl(longname: string): string;
226
  linkto(longname: string, linkText?: string): string;
227
  htmlsafe(str: string): string;
228
  find(spec: object): Doclet[];
229
  getSignature(doclet: Doclet): string;
230
}
231

232
// Deep object operations
233
function doop(original: object, extra?: object): object;
234

235
// Debug output
236
function dump(objects: any[]): string;
237
```
238

239
[Utilities](./utilities.md)
240

241
## Types
242

243
```javascript { .api }
244
// Core doclet interface
245
interface Doclet {
246
  kind: string;
247
  name: string;
248
  longname: string;
249
  description?: string;
250
  memberof?: string;
251
  scope?: string;
252
  meta: {
253
    path: string;
254
    filename: string;
255
    lineno: number;
256
    code: object;
257
  };
258
  // Additional properties based on doclet type
259
}
260

261
// Parser interface
262
interface Parser {
263
  parse(sourceFiles: string[], encoding?: string): Doclet[];
264
  addResult(doclet: Doclet): void;
265
  addAstNodeVisitor(visitor: Function): void;
266
  fireProcessingComplete(doclets: Doclet[]): void;
267
  clear(): void;
268
}
269

270
// AST Node interface  
271
interface ASTNode {
272
  type: string;
273
  nodeId?: string;
274
  parent?: ASTNode;
275
  enclosingScope?: ASTNode;
276
  [key: string]: any;
277
}
278

279
// TaffyDB database interface
280
interface TaffyDB {
281
  (): any;
282
  (query?: object): any;
283
  get(): any[];
284
  [key: string]: any;
285
}
286

287
// JSDoc options passed to templates
288
interface JSDocOptions {
289
  destination: string;
290
  encoding: string;
291
  template: string;
292
  readme?: string;
293
  package?: object;
294
  access?: string[];
295
  private?: boolean;
296
  query?: object;
297
  [key: string]: any;
298
}
299

300
// Tutorial system interfaces
301
interface TutorialRoot {
302
  title: string;
303
  children: Tutorial[];
304
}
305

306
interface Tutorial {
307
  title: string;
308
  name: string;
309
  content: string;
310
  children?: Tutorial[];
311
}
312

313
// Tag dictionary interface
314
interface TagDictionary {
315
  defineTag(name: string, options: object): void;
316
  [key: string]: any;
317
}
318

319
// Function parameter interface
320
interface Parameter {
321
  name: string;
322
  type?: { names: string[] };
323
  description?: string; 
324
  optional?: boolean;
325
  defaultvalue?: any;
326
}
327

328
// Return value interface  
329
interface Return {
330
  type?: { names: string[] };
331
  description?: string;
332
}
333

334
// Command-line options interface
335
interface CommandLineOptions {
336
  destination?: string;
337
  encoding?: string;
338
  access?: string[];
339
  configure?: string;
340
  debug?: boolean;
341
  help?: boolean;
342
  package?: string;
343
  pedantic?: boolean;
344
  private?: boolean;
345
  readme?: string;
346
  recurse?: boolean;
347
  template?: string;
348
  tutorials?: string;
349
  verbose?: boolean;
350
  version?: boolean;
351
  _?: string[];
352
}
353
```