{"id":14539,"library":"doxdox-parser-dox","title":"doxdox Dox Parser","description":"doxdox-parser-dox is a plugin package for the doxdox documentation generator, specifically designed to parse JavaScript source code comments formatted according to the Dox style. It acts as an adapter, allowing doxdox-core to process and extract documentation from files utilizing Dox-compliant comment blocks. Currently, this package is in its 4.0.0-preview.25 release, indicating active development towards a stable v4. The project appears to follow a rapid release cadence for its preview versions, frequently pushing hotfixes and minor feature updates. As a core parser for the doxdox ecosystem, it differentiates itself by providing a robust, opinionated parsing mechanism that feeds into doxdox's broader templating and rendering capabilities, enabling users to generate clean and modern API documentation from their existing Dox-formatted comments. It integrates seamlessly with the doxdox-core library, which is a required peer dependency.","status":"active","version":"4.0.0-preview.25","language":"javascript","source_language":"en","source_url":"git://github.com/docsbydoxdox/doxdox","tags":["javascript","doxdox","documentation","template","typescript"],"install":[{"cmd":"npm install doxdox-parser-dox","lang":"bash","label":"npm"},{"cmd":"yarn add doxdox-parser-dox","lang":"bash","label":"yarn"},{"cmd":"pnpm add doxdox-parser-dox","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for the doxdox ecosystem; this parser integrates with the core library.","package":"doxdox-core","optional":false}],"imports":[{"note":"The primary parser class is a named export, not a default export. Ensure named import syntax is used.","wrong":"import DoxParser from 'doxdox-parser-dox';","symbol":"DoxParser","correct":"import { DoxParser } from 'doxdox-parser-dox';"},{"note":"Import types separately using `import type` for TypeScript environments to avoid bundling unused code.","symbol":"ParserConfig","correct":"import type { ParserConfig } from 'doxdox-parser-dox';"},{"note":"The `Document` interface, representing the parsed output structure, is typically exposed by `doxdox-core` as it defines the common output format for all parsers.","symbol":"Document","correct":"import type { Document } from 'doxdox-core';"}],"quickstart":{"code":"import { DoxParser } from 'doxdox-parser-dox';\n\n// In a typical doxdox setup, the core library would manage parser instantiation and execution.\n// This quickstart demonstrates how the DoxParser itself works by calling its parse method directly.\n\n// Sample JavaScript/TypeScript code with Dox comments\nconst sampleCode = `\n/**\n * @file This is a test file demonstrating Dox comments.\n * @module Calculator\n */\n\n/**\n * Adds two numbers and returns their sum.\n *\n * This function takes two numeric arguments and\n * performs an addition operation.\n *\n * @param {number} a - The first operand.\n * @param {number} b - The second operand.\n * @returns {number} The sum of 'a' and 'b'.\n * @example\n * const result = add(5, 3); // result is 8\n */\nfunction add(a: number, b: number): number {\n  return a + b;\n}\n\n/**\n * Subtracts the second number from the first.\n *\n * @param {number} x - The number to subtract from.\n * @param {number} y - The number to subtract.\n * @returns {number} The difference (x - y).\n */\nconst subtract = (x: number, y: number): number => x - y;\n\n/**\n * Multiplies two numbers.\n * @private\n * @param {number} factor1 - The first factor.\n * @param {number} factor2 - The second factor.\n * @returns {number} The product.\n */\nfunction multiply(factor1: number, factor2: number): number {\n  return factor1 * factor2;\n}\n`;\n\nasync function parseDoxCode() {\n  const parser = new DoxParser();\n  const filePath = 'src/math-utils.ts'; // Represents the file path for context\n  const options = {}; // doxdox parser options, if any\n\n  console.log(`Parsing Dox-style comments from: ${filePath}\\n`);\n\n  try {\n    const parsedDocument = await parser.parse(sampleCode, filePath, options);\n\n    console.log('--- Parsed Document Output (Excerpt) ---');\n    console.log(`File: ${parsedDocument.file}`);\n    console.log(`Module: ${parsedDocument.module}`);\n    console.log('Methods:');\n    parsedDocument.methods.forEach((method, index) => {\n      console.log(`  ${index + 1}. Name: ${method.name}`);\n      console.log(`     Description: ${method.description}`);\n      if (method.params) {\n        console.log('     Parameters:');\n        method.params.forEach(param => {\n          console.log(`       - ${param.name} (${param.type}): ${param.description}`);\n        });\n      }\n      if (method.returns) {\n        console.log(`     Returns: ${method.returns[0].type} - ${method.returns[0].description}`);\n      }\n      if (method.tags) {\n          console.log(`     Tags: ${method.tags.map(tag => `@${tag.tag} ${tag.name}`).join(', ')}`);\n      }\n      console.log('');\n    });\n\n  } catch (error) {\n    console.error('Error during parsing:', error);\n  }\n}\n\nparseDoxCode();\n","lang":"typescript","description":"Demonstrates how to instantiate the DoxParser and use its `parse` method to extract documentation data from a string of code with Dox-style comments."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20.x or higher before installing or running doxdox-parser-dox.","message":"The minimum Node.js version required for doxdox v4 and its associated parsers has been increased to 20.x.","severity":"breaking","affected_versions":">=4.0.0-preview.21"},{"fix":"Pin exact package versions in your `package.json` to prevent unexpected breaking changes during preview releases. Monitor the project's changelog for updates if using in production.","message":"This package is currently in a preview state (v4.0.0-preview.X) and is subject to frequent updates, including potential API changes, before a stable v4 release.","severity":"gotcha","affected_versions":">=4.0.0-preview.1"},{"fix":"If you are directly interacting with the parser's programmatic interface or relying on the exact shape of the `Document` output, refer to the `doxdox-core` and `doxdox-parser-dox` typings or documentation for the latest interface specifications.","message":"The internal parser method signature and expected output data structure may have undergone breaking changes to align with a unified parser interface across doxdox v4.","severity":"breaking","affected_versions":">=4.0.0-preview.17"},{"fix":"Refer to the doxdox-core and doxdox-parser-dox typings or documentation regularly for updates to the data structures, especially when upgrading between preview versions.","message":"As a preview package, the exact structure of the parsed output (Document interface) or the ParserConfig object may evolve before a stable v4 release.","severity":"gotcha","affected_versions":">=4.0.0-preview.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the core library: `npm install doxdox-core@4.0.0-preview.25` or the corresponding compatible version.","cause":"doxdox-core is a peer dependency and must be installed separately from doxdox-parser-dox.","error":"Error: Cannot find module 'doxdox-core'"},{"fix":"Ensure your project is configured for ESM (e.g., by setting `\"type\": \"module\"` in `package.json` or using `.mjs` file extensions) and use `import` statements for all modules.","cause":"doxdox v4 and its parser plugins are designed for ES Modules (ESM) and do not support CommonJS `require()` statements.","error":"SyntaxError: require() not supported in ES module scope"},{"fix":"Upgrade Node.js to version 20.x or newer using a version manager like `nvm` or by installing a recent Node.js LTS release.","cause":"Your Node.js environment is running a version older than the minimum required 20.x for doxdox v4 components.","error":"Node.js version x.x.x is not supported. Required Node.js version is >=20."},{"fix":"Review your source code's Dox comments to ensure they adhere to standard formatting. If the issue persists with valid Dox syntax, consider reporting it to the doxdox project as a potential parser bug, referencing the affected preview version.","cause":"The parser encountered Dox comments or surrounding code patterns that it could not correctly interpret, possibly due to non-standard formatting or internal parser logic changes.","error":"Parsing failed due to comment/code pattern matching issues."}],"ecosystem":"npm"}