doxdox Dox Parser

4.0.0-preview.25 · active · verified Sun Apr 19

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.

Common errors

Warnings

Install

Imports

Quickstart

Demonstrates how to instantiate the DoxParser and use its `parse` method to extract documentation data from a string of code with Dox-style comments.

import { DoxParser } from 'doxdox-parser-dox';

// In a typical doxdox setup, the core library would manage parser instantiation and execution.
// This quickstart demonstrates how the DoxParser itself works by calling its parse method directly.

// Sample JavaScript/TypeScript code with Dox comments
const sampleCode = `
/**
 * @file This is a test file demonstrating Dox comments.
 * @module Calculator
 */

/**
 * Adds two numbers and returns their sum.
 *
 * This function takes two numeric arguments and
 * performs an addition operation.
 *
 * @param {number} a - The first operand.
 * @param {number} b - The second operand.
 * @returns {number} The sum of 'a' and 'b'.
 * @example
 * const result = add(5, 3); // result is 8
 */
function add(a: number, b: number): number {
  return a + b;
}

/**
 * Subtracts the second number from the first.
 *
 * @param {number} x - The number to subtract from.
 * @param {number} y - The number to subtract.
 * @returns {number} The difference (x - y).
 */
const subtract = (x: number, y: number): number => x - y;

/**
 * Multiplies two numbers.
 * @private
 * @param {number} factor1 - The first factor.
 * @param {number} factor2 - The second factor.
 * @returns {number} The product.
 */
function multiply(factor1: number, factor2: number): number {
  return factor1 * factor2;
}
`;

async function parseDoxCode() {
  const parser = new DoxParser();
  const filePath = 'src/math-utils.ts'; // Represents the file path for context
  const options = {}; // doxdox parser options, if any

  console.log(`Parsing Dox-style comments from: ${filePath}\n`);

  try {
    const parsedDocument = await parser.parse(sampleCode, filePath, options);

    console.log('--- Parsed Document Output (Excerpt) ---');
    console.log(`File: ${parsedDocument.file}`);
    console.log(`Module: ${parsedDocument.module}`);
    console.log('Methods:');
    parsedDocument.methods.forEach((method, index) => {
      console.log(`  ${index + 1}. Name: ${method.name}`);
      console.log(`     Description: ${method.description}`);
      if (method.params) {
        console.log('     Parameters:');
        method.params.forEach(param => {
          console.log(`       - ${param.name} (${param.type}): ${param.description}`);
        });
      }
      if (method.returns) {
        console.log(`     Returns: ${method.returns[0].type} - ${method.returns[0].description}`);
      }
      if (method.tags) {
          console.log(`     Tags: ${method.tags.map(tag => `@${tag.tag} ${tag.name}`).join(', ')}`);
      }
      console.log('');
    });

  } catch (error) {
    console.error('Error during parsing:', error);
  }
}

parseDoxCode();

view raw JSON →