{"id":15593,"library":"doctrine","title":"JSDoc Parser","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/eslint/doctrine","tags":["javascript"],"install":[{"cmd":"npm install doctrine","lang":"bash","label":"npm"},{"cmd":"yarn add doctrine","lang":"bash","label":"yarn"},{"cmd":"pnpm add doctrine","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import doctrine from 'doctrine';","symbol":"doctrine","correct":"const doctrine = require('doctrine');"},{"note":"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.","wrong":"import { parse } from 'doctrine';","symbol":"parse","correct":"const { parse } = require('doctrine');"},{"note":"For TypeScript usage, type definitions are available via the separate `@types/doctrine` package and not bundled with the library itself.","wrong":"import type { Tag, Type } from 'doctrine';","symbol":"Tag, Type (TypeScript types)","correct":"import type { Tag, Type } from '@types/doctrine';"}],"quickstart":{"code":"const doctrine = require('doctrine');\n\n// Example 1: Basic JSDoc parsing with multiple options\nconst comment1 = [\n  '/**', \n  ' * This is a test function.', \n  ' * @param {string} name - The user\\'s name.', \n  ' * @param {number} [age=30] - The user\\'s age (optional).', \n  ' * @returns {boolean} True if successful, false otherwise.', \n  ' * @deprecated Use `newName` instead.',\n  ' */'\n].join('\\n');\n\nconst ast1 = doctrine.parse(comment1, { unwrap: true, recoverable: true, sloppy: true, lineNumbers: true });\nconsole.log('AST 1 (parsed with full options):', JSON.stringify(ast1, null, 2));\n\n// Example 2: Parsing with specific tags only\nconst comment2 = [\n  '/**', \n  ' * Another function.', \n  ' * @param {Object} config - Configuration object.', \n  ' * @property {string} config.url - The URL to use.', \n  ' * @todo Implement error handling.', \n  ' */'\n].join('\\n');\n\nconst ast2 = doctrine.parse(comment2, { unwrap: true, tags: ['param', 'property'], recoverable: true });\nconsole.log('\\nAST 2 (filtered tags):', JSON.stringify(ast2, null, 2));","lang":"javascript","description":"Demonstrates basic JSDoc parsing with various options and filtering tags to obtain an AST representation."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 6.0.0 or higher.","message":"Version 3.0.0 dropped support for Node.js versions older than 6.0.0. Ensure your Node.js environment meets this minimum requirement.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Verify that the Apache License 2.0 is compatible with your project's licensing requirements.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Extract only the JSDoc comment block (e.g., `/** ... */`) as a string before passing it to `doctrine.parse()`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Include `{ sloppy: true }` in the options object when calling `doctrine.parse()` to correctly interpret optional parameters.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set `{ recoverable: true }` in the options object to allow parsing to continue after errors and report them in the AST's `problems` array.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you extract only the raw JSDoc comment block (e.g., `/** ... */`) as a string before invoking `doctrine.parse()`.","cause":"Attempting to pass an entire JavaScript file or an invalid string that is not a JSDoc comment to `doctrine.parse()`.","error":"Error: Expected JSDoc comment string, received non-comment input or full file."},{"fix":"Pass `{ sloppy: true }` in the options object to `doctrine.parse()` to allow this syntax.","cause":"Using optional parameter syntax with square brackets (e.g., `@param {string} [name]`) without enabling the `sloppy` parsing option.","error":"JSDoc parsing error: `@param {string} [foo]` syntax error"}],"ecosystem":"npm"}