JSDoc Parser

3.0.0 · active · verified Tue Apr 21

Doctrine is a specialized JavaScript parser focused solely on extracting and interpreting JSDoc comments from string inputs, rather than processing entire JavaScript files. Maintained by the ESLint team, its current stable version is 3.0.0. Releases appear irregularly, often aligned with maintenance or feature updates related to its integration within the broader ESLint ecosystem. Its primary differentiator is its granular approach to JSDoc parsing, offering fine-grained control over extraction options like unwrapping comment wrappers, filtering by specific tags, and handling parsing errors. It's designed for scenarios where only the documentation blocks need analysis, making it a foundational tool for linters, documentation generators, and code analysis tools that rely on JSDoc annotations.

Common errors

```
Error: Expected JSDoc comment string, received non-comment input or full file.
```
cause Attempting to pass an entire JavaScript file or an invalid string that is not a JSDoc comment to `doctrine.parse()`.

fix Ensure you extract only the raw JSDoc comment block (e.g., `/** ... */`) as a string before invoking `doctrine.parse()`.
```
JSDoc parsing error: `@param {string} [foo]` syntax error
```
cause Using optional parameter syntax with square brackets (e.g., `@param {string} [name]`) without enabling the `sloppy` parsing option.

fix Pass `{ sloppy: true }` in the options object to `doctrine.parse()` to allow this syntax.

Warnings

breaking Version 3.0.0 dropped support for Node.js versions older than 6.0.0. Ensure your Node.js environment meets this minimum requirement.
Fix: Upgrade your Node.js runtime to version 6.0.0 or higher.
breaking Version 2.0.0 changed the project's license from MIT to Apache License 2.0. Review the new license terms for compatibility with your project.
Fix: Verify that the Apache License 2.0 is compatible with your project's licensing requirements.
gotcha Doctrine is designed exclusively for parsing JSDoc comment strings, not entire JavaScript files. Passing a full script or arbitrary code will lead to parsing errors or incorrect AST output.
Fix: Extract only the JSDoc comment block (e.g., `/** ... */`) as a string before passing it to `doctrine.parse()`.
gotcha By default, `doctrine.parse()` does not tolerate optional parameters defined with square brackets (e.g., `@param {string} [name]`). Parsing such comments requires enabling 'sloppy' mode.
Fix: Include `{ sloppy: true }` in the options object when calling `doctrine.parse()` to correctly interpret optional parameters.
gotcha Without the `recoverable` option, `doctrine.parse()` will stop and potentially throw an error upon encountering syntax errors within the JSDoc comment. Errors will not be reported in the AST.
Fix: Set `{ recoverable: true }` in the options object to allow parsing to continue after errors and report them in the AST's `problems` array.

Install

npm install doctrine npm
yarn add doctrine yarn
pnpm add doctrine pnpm

Imports

doctrine
wrong:
```
import doctrine from 'doctrine';
```
correct:
```
const doctrine = require('doctrine');
```
Primary CommonJS export. Direct default ESM imports (`import doctrine from 'doctrine'`) may work via Node.js interop but explicit CommonJS `require` is the canonical approach.
parse
wrong:
```
import { parse } from 'doctrine';
```
correct:
```
const { parse } = require('doctrine');
```
The `parse` method is the main API, available as a property of the default export. Direct named ESM imports (`import { parse } from 'doctrine'`) are generally not supported for CommonJS modules without explicit ESM wrappers.
Tag, Type (TypeScript types)
wrong:
```
import type { Tag, Type } from 'doctrine';
```
correct:
```
import type { Tag, Type } from '@types/doctrine';
```
For TypeScript usage, type definitions are available via the separate `@types/doctrine` package and not bundled with the library itself.

Quickstart

Demonstrates basic JSDoc parsing with various options and filtering tags to obtain an AST representation.

const doctrine = require('doctrine');

// Example 1: Basic JSDoc parsing with multiple options
const comment1 = [
  '/**', 
  ' * This is a test function.', 
  ' * @param {string} name - The user\'s name.', 
  ' * @param {number} [age=30] - The user\'s age (optional).', 
  ' * @returns {boolean} True if successful, false otherwise.', 
  ' * @deprecated Use `newName` instead.',
  ' */'
].join('\n');

const ast1 = doctrine.parse(comment1, { unwrap: true, recoverable: true, sloppy: true, lineNumbers: true });
console.log('AST 1 (parsed with full options):', JSON.stringify(ast1, null, 2));

// Example 2: Parsing with specific tags only
const comment2 = [
  '/**', 
  ' * Another function.', 
  ' * @param {Object} config - Configuration object.', 
  ' * @property {string} config.url - The URL to use.', 
  ' * @todo Implement error handling.', 
  ' */'
].join('\n');

const ast2 = doctrine.parse(comment2, { unwrap: true, tags: ['param', 'property'], recoverable: true });
console.log('\nAST 2 (filtered tags):', JSON.stringify(ast2, null, 2));

view raw JSON →