{"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,"search_vec":"'1.0.0':24 'adapt':95 'aim':109 'annot':121 'approach':33 'associ':61 'assumpt':57 'avoid':54 'base':11 'block':20 'cadenc':104 'comment':19 'compar':34 'configur':43,82,112 'consum':51 'current':21 'custom':41 'defin':68 'design':13 'develop':65 'differenti':26 'doc':116 'docblock':1,4,98,118 'docblock-pars':3 'docblockpattern':85 'document':117 'empow':64 'endpattern':87 'enhanc':91 'explicit':102 'express':45 'extens':40 'fix':56 'flexibl':93 'follow':71 'format':99 'function':52 'interpret':75 'introduc':80 'javascript':115 'jsdoc':17,122 'jsdoc-styl':16 'less':31 'librari':12,108 'line':10,70 'line-bas':9 'linepattern':89 'make':55 'mani':36 'new':81 'notabl':79 'offer':29 'opinion':32 'option':83 'pars':15,113 'parser':2,5,38,119 'pattern':46 'precis':67 'provid':39,106 'regular':44 'releas':78,103 'signific':90 'solut':114 'specif':50 'stabl':111 'standalon':8 'startpattern':86 'style':18 'tag':49,63,73 'tag-specif':48 'type':120 'v1.0.0':77 'valu':60 'various':97 'version':23","created_at":"2026-04-20T01:52:36.770174+00:00","updated_at":"2026-04-20T01:52:36.770174+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/fkling/docblock-parser","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/docblock-parser","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}