or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-usage.mdcode-context.mdcomment-parsing.mddocumentation-generation.mdindex.mdjsdoc-tags.md
tile.json

index.mddocs/

Dox

Dox is a JavaScript documentation generator that parses JSDoc-style comments from JavaScript source code and outputs structured JSON data. Unlike opinionated documentation generators, dox provides raw JSON representation allowing developers to create custom documentation templates and workflows. It supports complex JSDoc type annotations, markdown formatting, and provides both command-line and programmatic interfaces.

Package Information

  • Package Name: dox
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install dox or npm install -g dox for CLI usage

Core Imports

const dox = require('dox');

// Or import specific functions
const { parseComments, parseTag, api } = require('dox');

For ES modules:

import dox from 'dox';

// Or import specific functions
import { parseComments, parseTag, api } from 'dox';

Basic Usage

const dox = require('dox');
const fs = require('fs');

// Read and parse JavaScript file
const source = fs.readFileSync('./myfile.js', 'utf8');
const comments = dox.parseComments(source);

// Output JSON structure
console.log(JSON.stringify(comments, null, 2));

// Generate markdown API documentation
const markdown = dox.api(comments);
console.log(markdown);

Command line usage:

# Parse from stdin
dox < myfile.js > documentation.json

# Generate markdown documentation
dox --api < myfile.js > README.md

# Debug mode for human-readable output
dox --debug < myfile.js

Architecture

Dox is built around several key components:

  • Comment Parser: Extracts and parses JSDoc-style comments from JavaScript source code
  • Tag System: Processes JSDoc tags (@param, @return, @api, etc.) with type parsing
  • Context Detection: Analyzes code to determine if comments document functions, methods, classes, etc.
  • Markdown Processing: Converts comment descriptions to HTML using markdown-it
  • CLI Interface: Command-line tool with multiple output formats
  • API Generator: Converts parsed comments to markdown documentation format

Capabilities

Comment Parsing

Core functionality for extracting and parsing JSDoc-style comments from JavaScript source code into structured JSON data.

/**
 * Parse comments in the given string of JavaScript code
 * @param {string} js - JavaScript source code to parse
 * @param {Object} [options] - Parsing options
 * @param {boolean} [options.raw] - Skip markdown processing
 * @param {boolean} [options.skipSingleStar] - Ignore /* */ comments
 * @param {string[]} [options.skipPrefixes] - Array of prefixes to skip
 * @returns {CommentObject[]} Array of parsed comment objects
 */
function parseComments(js, options);

interface CommentObject {
  tags: TagObject[];
  description: {
    full: string;    // Complete description with HTML
    summary: string; // First paragraph only  
    body: string;    // Remaining paragraphs
  };
  isPrivate: boolean;     // @api private tag present
  isConstructor: boolean; // @constructor tag present
  isClass: boolean;       // @class tag present
  isEvent: boolean;       // @event tag present
  ignore: boolean;        // Comment marked with !
  line: number;           // Starting line number
  codeStart: number;      // Line where code starts
  code: string;           // Code following comment
  ctx: ContextObject;     // Code context information
}

Comment Parsing

JSDoc Tag Processing

Advanced JSDoc tag parsing with support for complex type annotations and standard JSDoc tags.

/**
 * Parse a single JSDoc tag string into structured data
 * @param {string} str - Tag string to parse (e.g., "@param {string} name Description")
 * @returns {TagObject} Parsed tag object
 */
function parseTag(str);

/**
 * Parse JSDoc type string into structured types array
 * @param {string} str - Type string (e.g., "{string|number}")
 * @param {Object} [tag] - Tag object to populate with parsed data
 * @returns {Array} Array of parsed types
 */
function parseTagTypes(str, tag);

interface TagObject {
  type: string;           // Tag type (param, return, etc.)
  name?: string;          // Parameter/property name
  description: string;    // Tag description text
  types: Array;           // Parsed type information
  typesDescription: string; // Formatted HTML types
  optional: boolean;      // Parameter is optional
  nullable: boolean;      // Can be null
  nonNullable: boolean;   // Cannot be null
  variable: boolean;      // Variable arguments (...args)
  visibility?: string;    // public/private/protected
  string: string;         // Original tag string
}

JSDoc Tags

Code Context Analysis

Intelligent code analysis to determine the context of comments (functions, methods, classes, properties, etc.).

/**
 * Parse code context to determine type and structure
 * @param {string} str - Code string to analyze
 * @param {Object} [parentContext] - Parent context information
 * @returns {ContextObject|null} Context information or null
 */
function parseCodeContext(str, parentContext);

interface ContextObject {
  type: string;        // function, method, class, property, etc.
  name: string;        // Identifier name
  constructor?: string; // Constructor name for methods
  receiver?: string;   // Object receiving the method
  value?: string;      // Assigned value for properties
  string: string;      // Formatted context string
}

Code Context

API Documentation Generation

Convert parsed comment objects into formatted markdown documentation.

/**
 * Generate markdown API documentation from parsed comments
 * @param {CommentObject[]} comments - Array of parsed comment objects
 * @returns {string} Formatted markdown documentation
 */
function api(comments);

Documentation Generation

Command Line Interface

Full-featured CLI for processing JavaScript files and generating documentation.

# Basic usage
dox [options] < input.js > output.json

# Options:
# -r, --raw                      Output raw comments, leaving markdown intact
# -a, --api                      Output markdown readme documentation  
# -s, --skipPrefixes [prefixes]  Skip comments prefixed with these prefixes
# -d, --debug                    Output parsed comments for debugging
# -S, --skipSingleStar           Ignore /* ... */ comments
# -h, --help                     Display help information
# -V, --version                  Display version number

CLI Usage

Types

// Parsing options for parseComments
interface ParseOptions {
  raw?: boolean;           // Skip markdown processing
  skipSingleStar?: boolean; // Ignore /* */ comments  
  skipPrefixes?: string[]; // Array of prefixes to skip (default: ['jslint', 'jshint', 'eshint'])
}

// Individual comment parsing options
interface CommentOptions {
  raw?: boolean; // Skip markdown processing for this comment
}

// JSDoc tag object structure
interface TagObject {
  type: string;           // Tag type (param, return, etc.)
  name?: string;          // Parameter/property name
  description: string;    // Tag description text
  types: Array;           // Parsed type information
  typesDescription: string; // Formatted HTML types
  optional: boolean;      // Parameter is optional
  nullable: boolean;      // Can be null
  nonNullable: boolean;   // Cannot be null
  variable: boolean;      // Variable arguments (...args)
  visibility?: string;    // public/private/protected
  string: string;         // Original tag string
}

// Code context object structure
interface ContextObject {
  type: string;        // function, method, class, property, etc.
  name: string;        // Identifier name
  constructor?: string; // Constructor name for methods
  receiver?: string;   // Object receiving the method
  value?: string;      // Assigned value for properties
  string: string;      // Formatted context string
}