0
# JavaScript Parser
1

2
JSDoc's parser engine analyzes JavaScript source code, extracts JSDoc comments, and generates documentation objects (doclets). It supports modern ES6+ syntax and provides event-driven processing with extensive customization options.
3

4
## Capabilities
5

6
### Parser Creation
7

8
Functions for creating and configuring parser instances.
9

10
```javascript { .api }
11
/**
12
 * Create a new parser instance of the specified type
13
 * @param type - Parser type (default: 'js')
14
 * @returns Parser instance
15
 */
16
function createParser(type?: string): Parser;
17

18
/**
19
 * Available parser types
20
 */
21
const PARSERS: {
22
  js: string;
23
};
24
```
25

26
### Parser Class
27

28
Main parser class for processing JavaScript source files and generating doclets.
29

30
```javascript { .api }
31
class Parser {
32
  /**
33
   * Create a new Parser instance
34
   * @param builderInstance - AST builder (optional)
35
   * @param visitorInstance - AST visitor (optional) 
36
   * @param walkerInstance - AST walker (optional)
37
   */
38
  constructor(builderInstance?, visitorInstance?, walkerInstance?);
39

40
  /**
41
   * Parse source files and extract JSDoc comments
42
   * @param sourceFiles - Array of file paths or single file path
43
   * @param encoding - File encoding (default: 'utf8')
44
   * @returns Array of generated doclets
45
   */
46
  parse(sourceFiles: string | string[], encoding?: string): Doclet[];
47

48
  /**
49
   * Add a doclet to the results buffer
50
   * @param doclet - Doclet to add to results
51
   */
52
  addResult(doclet: Doclet): void;
53

54
  /**
55
   * Get current parsing results
56
   * @returns Array of doclets
57
   */
58
  results(): Doclet[];
59

60
  /**
61
   * Clear parser state and results
62
   */
63
  clear(): void;
64

65
  /**
66
   * Fire processing complete event
67
   * @param doclets - Final doclet array
68
   */
69
  fireProcessingComplete(doclets: Doclet[]): void;
70
}
71
```
72

73
### AST Node Visitor Management
74

75
Methods for managing custom AST node visitors during parsing.
76

77
```javascript { .api }
78
/**
79
 * Add custom AST node visitor
80
 * @param visitor - Visitor function for AST nodes
81
 */
82
addAstNodeVisitor(visitor: Function): void;
83

84
/**
85
 * Get all registered AST node visitors
86
 * @returns Array of visitor functions
87
 */
88
getAstNodeVisitors(): Function[];
89
```
90

91
### Symbol Resolution
92

93
Advanced methods for resolving symbol relationships and scope.
94

95
```javascript { .api }
96
/**
97
 * Resolve what a node is a member of
98
 * @param node - AST node
99
 * @returns Object with memberof and basename information
100
 */
101
astnodeToMemberof(node: ASTNode): {
102
  memberof?: string;
103
  basename?: string;
104
};
105

106
/**
107
 * Resolve what "this" refers to for a given node
108
 * @param node - AST node containing "this" reference
109
 * @returns Longname of the enclosing context
110
 */
111
resolveThis(node: ASTNode): string;
112

113
/**
114
 * Resolve parent objects for a property node
115
 * @param node - Property AST node
116
 * @returns Array of parent doclets
117
 */
118
resolvePropertyParents(node: { parent: ASTNode }): Doclet[];
119

120
/**
121
 * Resolve variable scope for a node
122
 * @param node - AST node
123
 * @param basename - Variable basename
124
 * @returns Scope longname
125
 */
126
resolveVar(node: { enclosingScope?: ASTNode; type: string }, basename: string): string;
127

128
/**
129
 * Resolve enum properties
130
 * @param e - Event object with doclet and code information
131
 */
132
resolveEnum(e: { doclet: Doclet; code: { node: ASTNode } }): void;
133
```
134

135
### Doclet Reference Management
136

137
Methods for managing doclet references and lookups.
138

139
```javascript { .api }
140
/**
141
 * Add doclet reference for node lookup
142
 * @param e - Event object with doclet and code information
143
 */
144
addDocletRef(e: {
145
  doclet?: Doclet;
146
  code?: { node: ASTNode };
147
}): void;
148
```
149

150
## Parser Events
151

152
The parser emits events during processing that can be handled by plugins.
153

154
### Core Events
155

156
```javascript { .api }
157
// Event interfaces
158
interface ParseBeginEvent {
159
  sourcefiles: string[];
160
}
161

162
interface FileBeginEvent {
163
  filename: string;
164
}
165

166
interface JSDocCommentFoundEvent {
167
  comment: string;
168
  lineno: number;
169
  columnno: number;
170
  filename: string;
171
}
172

173
interface SymbolFoundEvent {
174
  // Symbol information
175
}
176

177
interface NewDocletEvent {
178
  doclet: Doclet;
179
}
180

181
interface FileCompleteEvent {
182
  filename: string;
183
  source?: string;
184
}
185

186
interface ParseCompleteEvent {
187
  sourcefiles: string[];
188
  doclets: Doclet[];
189
}
190

191
interface ProcessingCompleteEvent {
192
  doclets: Doclet[];
193
}
194
```
195

196
### Event Usage Examples
197

198
```javascript
199
// Adding event handlers
200
parser.on('parseBegin', (e) => {
201
  console.log('Starting to parse:', e.sourcefiles);
202
});
203

204
parser.on('jsdocCommentFound', (e) => {
205
  console.log(`Found comment at ${e.filename}:${e.lineno}`);
206
});
207

208
parser.on('newDoclet', (e) => {
209
  console.log('Generated doclet:', e.doclet.longname);
210
});
211
```
212

213
## Doclet Interface
214

215
Structure of documentation objects generated by the parser.
216

217
```javascript { .api }
218
interface Doclet {
219
  // Core properties
220
  kind: string;           // 'function', 'class', 'member', etc.
221
  name: string;           // Symbol name
222
  longname: string;       // Full qualified name
223
  description?: string;   // Description text
224
  
225
  // Hierarchy
226
  memberof?: string;      // Parent symbol longname
227
  scope?: string;         // 'static', 'instance', 'inner', 'global'
228
  
229
  // Metadata
230
  meta: {
231
    path: string;         // File path
232
    filename: string;     // File name
233
    lineno: number;       // Line number
234
    code: {
235
      name?: string;      // Code symbol name
236
      type: string;       // AST node type
237
      value?: any;        // Symbol value
238
      paramnames?: string[]; // Parameter names
239
    };
240
  };
241
  
242
  // Function-specific
243
  params?: Parameter[];   // Function parameters
244
  returns?: Return[];     // Return information
245
  
246
  // Class-specific
247
  classdesc?: string;     // Class description
248
  
249
  // Type information
250
  type?: {
251
    names: string[];      // Type names
252
  };
253
  
254
  // Documentation flags
255
  undocumented?: boolean; // No JSDoc comment
256
  ignore?: boolean;       // Should be ignored
257
  inherited?: boolean;    // Inherited member
258
  virtual?: boolean;      // Virtual/abstract member
259
}
260

261
interface Parameter {
262
  name: string;
263
  type?: { names: string[] };
264
  description?: string;
265
  optional?: boolean;
266
  defaultvalue?: any;
267
}
268

269
interface Return {
270
  type?: { names: string[] };
271
  description?: string;
272
}
273
```
274

275
## Usage Examples
276

277
### Basic Parser Usage
278

279
```javascript
280
const parser = require('jsdoc/src/parser');
281
const env = require('jsdoc/env');
282

283
// Set up environment
284
env.opts = { encoding: 'utf8' };
285
env.conf = {
286
  source: {
287
    includePattern: '\\.js$',
288
    excludePattern: 'node_modules/'
289
  }
290
};
291

292
// Create and use parser
293
const jsdocParser = parser.createParser();
294
const doclets = jsdocParser.parse(['src/myfile.js']);
295

296
console.log(`Generated ${doclets.length} doclets`);
297
doclets.forEach(doclet => {
298
  console.log(`${doclet.kind}: ${doclet.longname}`);
299
});
300
```
301

302
### Advanced Parser with Events
303

304
```javascript
305
const parser = require('jsdoc/src/parser');
306
const env = require('jsdoc/env');
307

308
// Configure environment
309
env.conf = {
310
  source: { includePattern: '\\.js$' },
311
  plugins: ['plugins/markdown']
312
};
313

314
// Create parser with event handlers
315
const jsdocParser = parser.createParser();
316

317
jsdocParser.on('parseBegin', (e) => {
318
  console.log('Starting parse of:', e.sourcefiles);
319
});
320

321
jsdocParser.on('newDoclet', (e) => {
322
  if (!e.doclet.undocumented) {
323
    console.log(`Documented: ${e.doclet.longname}`);
324
  }
325
});
326

327
jsdocParser.on('parseComplete', (e) => {
328
  console.log(`Parse complete: ${e.doclets.length} doclets generated`);
329
});
330

331
// Parse files
332
const doclets = jsdocParser.parse(['src/**/*.js']);
333
```
334

335
### Custom AST Node Visitor
336

337
```javascript
338
const parser = require('jsdoc/src/parser');
339

340
// Create parser
341
const jsdocParser = parser.createParser();
342

343
// Add custom visitor for specific node types
344
jsdocParser.addAstNodeVisitor(function(node, e, parser, currentSourceName) {
345
  if (node.type === 'FunctionExpression' && node.id && node.id.name) {
346
    console.log(`Found function expression: ${node.id.name}`);
347
  }
348
});
349

350
// Parse with custom visitor
351
const doclets = jsdocParser.parse(['myfile.js']);
352
```
353

354
### Working with Doclets
355

356
```javascript
357
// Filter doclets by type
358
const functions = doclets.filter(d => d.kind === 'function');
359
const classes = doclets.filter(d => d.kind === 'class');
360

361
// Find specific doclet by longname
362
const mainClass = doclets.find(d => d.longname === 'MyClass');
363

364
// Get all members of a class
365
const members = doclets.filter(d => d.memberof === 'MyClass');
366

367
// Get undocumented symbols
368
const undocumented = doclets.filter(d => d.undocumented);
369
```
370

371
## Integration with Other Systems
372

373
### Plugin Integration
374

375
```javascript
376
// Parser automatically loads plugins
377
env.conf.plugins = ['plugins/markdown', 'plugins/overloadHelper'];
378

379
const jsdocParser = parser.createParser();
380
// Plugins are now active during parsing
381
```
382

383
### Template Integration
384

385
```javascript
386
// Doclets are passed to template publish function
387
function publish(data, opts) {
388
  // data is a TaffyDB collection of doclets
389
  const allDoclets = data().get();
390
  
391
  allDoclets.forEach(doclet => {
392
    if (doclet.kind === 'function') {
393
      generateFunctionDoc(doclet);
394
    }
395
  });
396
}
397
```
398

399
## Error Handling
400

401
### Parser Error Types
402

403
- **Syntax Errors**: Invalid JavaScript syntax in source files
404
- **JSDoc Errors**: Malformed JSDoc comments or tags
405
- **File Errors**: Missing files, encoding issues
406
- **Plugin Errors**: Plugin loading or execution failures
407

408
### Error Handling Examples
409

410
```javascript
411
try {
412
  const doclets = jsdocParser.parse(['problematic-file.js']);
413
} catch (error) {
414
  if (error.message.includes('Unexpected token')) {
415
    console.error('Syntax error in source file');
416
  } else {
417
    console.error('Parser error:', error.message);
418
  }
419
}
420

421
// Use pedantic mode to treat warnings as errors
422
env.opts.pedantic = true;
423
```