{"id":13075,"library":"docblock-parser","title":"Docblock Parser","description":"docblock-parser is a standalone, line-based library designed for parsing JSDoc-style comment blocks. Currently at version 1.0.0, it differentiates itself by offering a less opinionated approach compared to many other parsers, providing extensive customization through configurable regular expression patterns and tag-specific consumer functions. It avoids making fixed assumptions about the values associated with tags, empowering developers to precisely define how lines following a tag are interpreted. The v1.0.0 release notably introduced new configuration options for `docblockPattern`, `startPattern`, `endPattern`, and `linePattern`, significantly enhancing its flexibility for adapting to various docblock formats. While no explicit release cadence is provided, the library aims for stable, configurable parsing solutions.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/fkling/docblock-parser","tags":["javascript","docs","documention","docblock","parser","type","annotation","jsdoc"],"install":[{"cmd":"npm install docblock-parser","lang":"bash","label":"npm"},{"cmd":"yarn add docblock-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add docblock-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is primarily CommonJS. For ESM environments, ensure proper CommonJS interop or use dynamic import.","wrong":"import docblockParser from 'docblock-parser';","symbol":"docblockParser","correct":"const docblockParser = require('docblock-parser');"},{"note":"The `parse` method is a property of the main exported function, not a named export. It can also be called directly if no custom config is needed.","wrong":"const { parse } = require('docblock-parser');","symbol":"docblockParser.parse","correct":"const parser = require('docblock-parser');\nparser.parse(docstring);"},{"note":"Helper consumers like `booleanTag` are properties of the main `docblockParser` export, not top-level named exports.","wrong":"import { booleanTag } from 'docblock-parser';","symbol":"docblockParser.booleanTag","correct":"const docblockParser = require('docblock-parser');\nconst config = { tags: { public: docblockParser.booleanTag } };"}],"quickstart":{"code":"const docblockParser = require('docblock-parser');\n\nconst docstring = [\n  '/**', \n  ' * Some free text for the block.',\n  ' * This can span multiple lines.',\n  ' *',\n  ' * @public',\n  ' * @extends MyBaseClass',\n  ' * @multiline-example',\n  ' * function exampleFunc() {',\n  ' *   console.log(\"Hello\");',\n  ' * }',\n  ' *',\n  ' * With additional description after the code.',\n  ' *',\n  ' * @param {string} foo - The first parameter.',\n  ' * @param {number} bar - The second parameter.',\n  ' * @returns {boolean} True if successful, false otherwise.',\n  ' */'\n].join('\\n');\n\nconst result = docblockParser({\n  tags: {\n    public: docblockParser.booleanTag,\n    extends: docblockParser.singleParameterTag,\n    'multiline-example': docblockParser.multilineTilTag,\n    param: docblockParser.multilineTilTag, // JSDoc @param structure is handled by multilineTilTag\n    returns: docblockParser.multilineTilTag // JSDoc @returns structure is handled by multilineTilTag\n  }\n}).parse(docstring);\n\nconsole.log(JSON.stringify(result, null, 2));","lang":"javascript","description":"This example demonstrates parsing a multi-line docblock with custom tag consumers for standard JSDoc tags like `@public`, `@extends`, `@param`, and `@returns`, as well as a custom `multiline-example` tag."},"warnings":[{"fix":"Review the new `docblockPattern`, `startPattern`, `endPattern`, and `linePattern` configuration options in the README for custom parsing scenarios.","message":"Although not explicitly labeled a breaking change, version 1.0.0 introduced configurable patterns for `docblockPattern`, `startPattern`, `endPattern`, and `linePattern`. While existing defaults are maintained, custom configurations from prior versions (if any) might need review if they relied on internal, non-exposed patterns.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always check `Array.isArray(result.text)` and `Array.isArray(result.tags[tagName])` if your logic depends on the cardinality of these fields. Design your consumers to consistently return a single type (e.g., always an array) if uniform handling is required.","message":"The return type of the `text` field in the parsed result can be either a `string` or an `Array` of strings, depending on whether the docblock contains multiple distinct sections of free text. Similarly, tag values can be single items or arrays if a tag appears multiple times.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `const docblockParser = require('docblock-parser');` for robust compatibility in Node.js. If using ESM, ensure your build setup correctly handles CommonJS module interop or consider using dynamic `import('docblock-parser')`.","message":"The library is primarily designed for CommonJS (`require`). While modern Node.js environments and bundlers often provide CommonJS interop for ESM `import` statements, direct `import docblockParser from 'docblock-parser';` might lead to issues without proper configuration (e.g., `type: module` in `package.json` and a default export).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `const docblockParser = require('docblock-parser');` is used and the variable name matches. If you're trying to call the `parse` method directly, it's `docblockParser.parse(docstring)` or `docblockParser(config).parse(docstring)`.","cause":"Attempting to call `docblockParser()` when it's `undefined` or not correctly imported.","error":"TypeError: docblockParser is not a function"},{"fix":"Verify that `docblock-parser` is correctly installed via `npm install docblock-parser` and that the `require('docblock-parser')` path is correct relative to your file.","cause":"This usually means `docblockParser` itself is `undefined` because the `require` call failed to resolve the module or returned an unexpected value.","error":"TypeError: Cannot read properties of undefined (reading 'parse')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}