DocBox Documentation Generation

When to Use This Skill

Use this skill when:

• Setting up DocBox to generate API docs for a BoxLang or CFML project
• Choosing and configuring HTML, JSON, UML, or CommandBox output strategies
• Running DocBox via code, CLI, or a build task
• Excluding test/build paths from generated docs
• Creating a custom output strategy

Language Mode Reference

Examples use BoxLang (.bx) syntax by default. Adapt for your target language:

Concept	BoxLang (.bx)	CFML (.cfc)
Class declaration	class [extends="..."] {	component [extends="..."] {
DI annotation	@inject above property name="svc";	property name="svc" inject="svc";
View templates	.bxm suffix	.cfm / .cfml suffix
Tag prefix	<bx:if>, <bx:output>, <bx:set>	<cfif>, <cfoutput>, <cfset>

CFML Compat Mode: With BoxLang + CFML Compat module, .bx and .cfc files coexist freely. BoxLang-native classes use class {} (.bx files); CFML-compat classes use component {} (.cfc files).

Installation

# BoxLang (recommended)
box install bx-docbox

# CommandBox module (for CLI usage)
box install commandbox-docbox

# CFML project dev dependency
box install docbox --saveDev

Core API

DocBox.init( [strategy], [properties] )        → DocBox
DocBox.addStrategy( strategy, [properties] )    → DocBox (chainable)
DocBox.generate( source, mapping, [excludes], [throwOnError] ) → DocBox
DocBox.getStrategies()                          → array

Basic Usage

Single HTML Strategy

new docbox.DocBox()
    .addStrategy( "HTML", {
        projectTitle       : "My App API",
        projectDescription : "Public API reference for My App",
        outputDir          : expandPath( "/docs/html" ),
        theme              : "default"   // or "frames"
    } )
    .generate(
        source  : expandPath( "/app" ),
        mapping : "app",
        excludes: "(tests|specs|build|\.git)"
    )

Multiple Strategies in One Pass

new docbox.DocBox()
    .addStrategy( "HTML", {
        projectTitle : "My App API",
        outputDir    : expandPath( "/docs/html" ),
        theme        : "default"
    } )
    .addStrategy( "JSON", {
        projectTitle : "My App API",
        outputDir    : expandPath( "/docs/json" )
    } )
    .addStrategy( "UML", {
        projectFile  : expandPath( "/docs/uml/myapp.uml" )
    } )
    .generate(
        source  : expandPath( "/app" ),
        mapping : "app",
        excludes: "(tests|build)"
    )

Multiple Source Directories

new docbox.DocBox()
    .addStrategy( "HTML", {
        projectTitle : "My App API",
        outputDir    : expandPath( "/docs" )
    } )
    .generate(
        source : [
            { dir: expandPath( "/app/models" ),   mapping: "app.models" },
            { dir: expandPath( "/app/services" ),  mapping: "app.services" },
            { dir: expandPath( "/app/handlers" ),  mapping: "app.handlers" }
        ],
        excludes: "(tests|specs)"
    )

Output Strategies

HTML Strategy

The most common output. Produces navigable HTML documentation.

Property	Type	Required	Default	Description
outputDir	string	✅	—	Absolute path to the output directory
projectTitle	string	No	"Untitled"	Browser title and page heading
projectDescription	string	No	""	Subtitle/description displayed in header
theme	string	No	"default"	"default" or "frames"

Default theme — Modern Alpine.js single-page app:

• Dark/light mode toggle
• Real-time method search (Enter / Shift+Enter)
• Method tabs: All / Public / Private / Static / Abstract
• Bootstrap 5, fully responsive

Frames theme — Classic 3-panel frameset layout:

• Package navigation sidebar (left frame)
• Member list frame (top right)
• Detail frame (bottom right)

// Default (SPA)
.addStrategy( "HTML", {
    outputDir : expandPath( "/docs" ),
    theme     : "default"
} )

// Classic frames
.addStrategy( "HTML", {
    outputDir : expandPath( "/docs" ),
    theme     : "frames"
} )

JSON Strategy

Generates machine-readable JSON files for tooling integration.

Output files:

• overview-summary.json — index of all packages and classes
• {package}/package-summary.json — all classes in a package
• {package}/{ClassName}.json — full documentation for one class

.addStrategy( "JSON", {
    projectTitle : "My API",
    outputDir    : expandPath( "/docs/json" )
} )

UML Strategy

Generates an Eclipse UML2Tools-compatible .uml XML file.

Note: UML2Tools is no longer actively developed. This strategy is primarily for legacy tooling.

.addStrategy( "UML", {
    projectFile : expandPath( "/docs/myapp.uml" )
} )

CommandBox Strategy

Specialized HTML output for CommandBox CLI modules — uses "namespace" / "command" terminology instead of "package" / "class".

new docbox.DocBox()
    .addStrategy( "CommandBox", {
        projectTitle : "My CommandBox Module",
        outputDir    : expandPath( "/docs/commands" )
    } )
    .generate(
        source  : expandPath( "/modules/my-module/commands/" ),
        mapping : "my-module.commands"
    )

Custom Strategy

Extend AbstractTemplateStrategy and implement IStrategy:

// myapp/strategy/MyCustomStrategy.cfc
class extends="docbox.strategy.AbstractTemplateStrategy" {

    /**
     * Execute documentation generation.
     * @metadata  Query of all component metadata
     */
    IStrategy function run( required query metadata ) {
        // metadata columns: package, name, metadata, type, extends, implements
        for ( var row in metadata ) {
            // generate your custom output for each component
        }
        return this
    }
}

Register it by passing the instance directly:

new docbox.DocBox()
    .addStrategy( new myapp.strategy.MyCustomStrategy( outputDir: expandPath("/docs/custom") ) )
    .generate( source: expandPath("/app"), mapping: "app" )

Run from BoxLang CLI

# Minimal
boxlang module:docbox \
    --source=/path/to/code \
    --mapping=myapp

# Full options
boxlang module:docbox \
    --source=/path/to/code \
    --mapping=myapp \
    --output-dir=/docs \
    --project-title="My API" \
    --theme=default \
    --excludes="(tests|build|\.git)"

# Multiple sources (comma-separated)
boxlang module:docbox \
    --source="/app/models,/app/services" \
    --mapping=app \
    --output-dir=/docs

Run from CommandBox

# Install the CommandBox module once
box install commandbox-docbox

# Basic run
box docbox generate source=/app mapping=app outputDir=/docs

# With options
box docbox generate \
    source=/app \
    mapping=app \
    outputDir=/docs \
    projectTitle="My API" \
    excludes="(tests|build)"

ColdBox Build Task Example

// build/GenerateDocs.cfc
class {

    function run() {

        print.line( "📚 Generating API documentation..." )

        new docbox.DocBox()
            .addStrategy( "HTML", {
                projectTitle       : "My ColdBox App",
                projectDescription : "Internal API Reference",
                outputDir          : expandPath( "/docs" ),
                theme              : "default"
            } )
            .generate(
                source   : expandPath( "/app" ),
                mapping  : "app",
                excludes : "(tests|specs|build|node_modules|\.git)"
            )

        print.greenLine( "✅ Docs generated at /docs" )
    }
}

generate() Parameters Reference

Parameter	Type	Required	Description
source	string | array	✅	Path to source dir or array of {dir, mapping} structs
mapping	string	✅ (when source is string)	ColdFusion/BoxLang mapping for the source root
excludes	string	No	Java regex applied to relative file paths (e.g., "(tests|build)")
throwOnError	boolean	No (false)	Throw on parsing errors instead of silently skipping

Excludes Pattern Examples

// Exclude test and build directories
excludes: "(tests|specs|build)"

// Exclude dot folders and generated code
excludes: "(\.git|\.github|node_modules|generated)"

// Exclude specific packages
excludes: "(tests|mocks|stubs|util\.internal)"

Troubleshooting

Symptom	Likely Cause	Fix
No output generated	Wrong source path	Use expandPath() for absolute paths
Missing classes	Class inside excluded pattern	Review excludes regex
Blank descriptions	Comment uses /* */ not /** */	Use double-star comment block
Strategy not found	Typo in strategy alias	Use exact strings: "HTML", "JSON", "UML", "CommandBox"
Parse errors logged	Invalid CFML/BoxLang syntax	Set throwOnError: true to see details