1 of 21

DocBox

Introduction

DocBox is a JavaDoc-style documentation generator for your BoxLang and CFML Applications.

📚 DocBox reads class metadata and structured comments and outputs documentation in an HTML, JSON, or UML (diagram) format. You can see our live docs here: https://s3.amazonaws.com/apidocs.ortussolutions.com/docbox/5.0.0/index.html

💻 System Requirements

BoxLang 1.8+
Lucee 5+ / Adobe ColdFusion 2023+ (CFML Support)

🔢 Versioning

DocBox is maintained under the Semantic Versioning guidelines as much as possible. Releases will be numbered in the following format:

And constructed with the following guidelines:

Breaking backward compatibility bumps the major (and resets the minor and patch)
New additions without breaking backward compatibility bumps the minor (and resets the patch)
Bug fixes and misc changes bumps the patch

Apache 2 License:

💻 Code:
🐛 Issues:
💬 Community:

DocBox is professional open source software backed by offering services like:

🛠️ Custom Development
🎯 Professional Support & Mentoring
📖 Training

Because of His grace, this project exists. If you don't like this, don't read it; it's not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God." Romans 5:5

Release History

A brief history in time of our major releases

In this section, you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions, use the version switcher at the top left of this documentation book. Here is a breakdown of our major version releases.

Version 5.0

Major release adding full BoxLang support, modern HTML themes with dark mode, enhanced UI/UX with real-time search, complete relationship documentation, and comprehensive developer experience improvements.

Version 4.0

This major bump was to deprecate some CFML engines

Version 3.0

Added a JSON strategy in preparation for multiple output strategies we will support. Updated build processes and a new outlook for the future of the project.

Version 2.0

The migration from ColdDoc into DocBox.

What's New With 4.1.0

Adobe 2023 Testing and Support
New Github Actions
New supporting files

What's New With 4.0.0

BREAKING

Dropped support for Adobe 2016. Adobe doesn't support ACF 16 anymore, so neither do we.

NEW

Added support for Adobe 2021
Added support for @myCustomTag custom docblock tags on methods. (Already supported on components and properties, but missing on methods).
Added GitHub Actions CI for automated testing, format checking, releases and more

Fixes support for Adobe 2018. (Mainly in the CommandBox strategy.)

Contributing

Learn how to contribute to the DocBox project by submitting pull requests, reporting issues, and writing tests.

🤝 There are several ways you can help in the development of DocBox!

🔧 Send a pull request
🐛 Submit a bug or feature request to our Jira issue tracker
✅

Fork or the
Clone the repository fork to your machine - git clone git@github.com:ME/DocBox.git
Create a feature/ or patch/

DocBox has a suite of Testbox specs validating that it works as expected. New features and bug fix PRs should (ideally) contain accompanying tests. Here's how to do that via CommandBox:

After cloning the repo, run box install to install development dependencies
Run box start to boot a test server
Run box testbox run

Getting Started

Installation

Get started with installing DocBox in your BoxLang or CFML application.

DocBox can be installed and used in multiple ways, depending on your needs. The recommended method for most users is to install DocBox as a BoxLang module, which provides access to the powerful CLI tool for generating documentation. However, you can also use it as a CommandBox module or a standalone CFML application.

🦤 BoxLang Module Installation (Recommended for CLI)

DocBox 5.0+ can be installed as a native BoxLang core module, providing access to the powerful CLI tool.

CommandBox Web Runtimes

box install bx-docbox

BoxLang OS Runtime

install-bx-module bx-docbox

Once installed, you can use the boxlang module:docbox CLI command to generate documentation. See the BoxLang CLI Tool page for complete usage details and examples.

BoxLang CLI Tool Examples

DocBox includes a native BoxLang CLI module for generating documentation:

# Basic usage
boxlang module:docbox --source=/path/to/code --mapping=myapp --output-dir=/docs

# With project title and excludes
boxlang module:docbox --source=/src --mapping=myapp \
                       --excludes="(tests|build)" \
                       --output-dir=/docs \
                       --project-title="My API"

# Multiple source mappings
boxlang module:docbox --mappings:v1=/src/v1/models \
                       --mappings:v2=/src/v2/models \
                       --output-dir=/docs

# Using frames theme
boxlang module:docbox --source=/src --mapping=app \
                       --output-dir=/docs \
                       --theme=frames

# Show help
boxlang module:docbox --help

# Show version
boxlang module:docbox --version

CommandBox Module

We also have a CommandBox module called DocBox Commands, which enables generating documentation from the CLI as a CommandBox command.

Run box install commandbox-docbox to install the docbox command namespace
Run docbox help to get a list of commands
Run docbox generate help to show help for the docbox generate command

Please see the for more info.

Installing and using DocBox consists of three main steps:

For best results, use to run box install docbox --saveDev in your app root.

Alternatively, you can download the DocBox source code and drop it into a docbox folder in your application.

If DocBox is not installed in the root of your application, you will need to create a docbox mapping that points to the DocBox source code location:

Then you can access DocBox via the mapping you created.

BoxLang CLI Tool

Get started with the BoxLang CLI tool for generating documentation

🦤 DocBox 5.0+ includes a native BoxLang module with a powerful CLI tool for generating documentation directly from the command line.

DocBox can be installed as a BoxLang core module using the bx-docbox slug:

Once installed, the boxlang module:docbox command becomes available for generating documentation.

Option

Short

Description

Annotating Your Code

Learn how to annotate your BoxLang or CFML code for DocBox documentation generation

📝 DocBox reads your classes and creates documentation according to your objects, inheritance, implementations, functions, arguments, comments and metadata. We try to follow the JavaDoc style of annotations even though it is not 100% compatible yet.

💬 DocBox Comments

DocBox comments may be placed above any class declaration, property, function, or argument which we want to document.

/**
 * This is a Javadoc compliant comment for DocBox
 */

These comments are commonly made up of two sections:

The description of what we're commenting on
The standalone block tags (marked with the @ symbol) which describe specific meta-data
Also all core engine attributes to components, properties, functions and arguments will be documented automatically for you.

For the full JavaDoc spec click here:

Please note that BoxLang allows you to use both documentation annotation and code annotation styles.

This is a simple component declaration where we define the hint for the component and add block tags like @author . All attributes to the component will be documented for you as name-value pairs on the final output.

Properties also have comments and you can add @ blocks as well.

Functions can have a variety of block tags alongside the main description of the function. Also notice that each argument can also be documented via the @argName block tag.

Arguments can also have multiple annotations for documentation or semantic usage purposes.

This is done by using a . period delimiter and then adding another block name or semantic name to use.

Here are some of the core blocks that can be used in DocBox:

Tag

Explanation

Here are some blocks that ONLY DocBox can read:

Tag

Explanation

DocBox supports standard JavaDoc tags and recognizes custom annotations for enhanced documentation.

The @doc.type annotation allows you to specify generic types for complex return types and arguments. This is especially useful for documenting collections and typed data structures.

Syntax:

Examples:

Document arrays with specific element types:

Document structs with key/value types:

Document typed parameters:

Document complex struct parameters:

BoxLang also supports inline doc.type attributes:

For nested or complex types:

Be Specific: Use concrete types instead of generic "Any" when possible
Consistency: Use the same naming convention throughout your codebase
Documentation: Combine with @return or parameter hints for full context

Output Formats

JSON Output

Generate JSON output for easy documentation imports into other documentation tools and platforms.

📋 Generate machine-readable JSON documentation for easy imports into other documentation tools and platforms.

Begin by creating an instance of DocBox:

The following are the properties for this strategy:

projectTitle : Used in the top-level overview-summary.json

JSON Schema

Understanding the output format of the DocBox JSON strategy

The JSON strategy outputs three types of files:

Overview Summary
Package Summary

DocBox's JSON strategy outputs a single overview-summary.json file in the root of the configured outputDir directory that documents all packages (component directories) and classes in the configured source.

This overview-summary.json file will match the following schema:

See an example at

DocBox's JSON strategy outputs a package-summary.json file for every directory found in the configured source directory that contains at least one ColdFusion component.

source/autos/autoBuilder.cfc will generate a docs/source/autos/package-summary.json

This package-summary.json file will match the following schema:

See an example at

DocBox's JSON strategy outputs a single class.json file for every .cfc component found in the configured source directory.

The name of the file will reflect the component name, and the location will match the source directory hierarchy:

source/app/autos/autoBuilder.cfc becomes docs/source/app/autos/autoBuilder.json
source/main.cfc becomes docs/source/main.json

Each component documentation file will match the following schema:

See an example at

UML Output

Generate an XML file for graphing your application via Eclipse UML2Tools

📐 Generate an XML file for graphing your application via Eclipse UML2Tools

UML2 Tools hasn't been developed for Eclipse since 2008. This strategy is now more for reference than anything else.

This is a documentation strategy that ultimately lets you generate UML diagrams from the CFCs that you have written. That being said, it does not actually generate diagrams.

What this template startegy does is generate the XML file the Eclipse UML2 Tools that stores the information about your domain - the classes, the associations, the inheritence hierarchy, etc. From there it is very easy with UML2 Tools to generate UML diagrams like Class Diagrams, Sequence Diagrams, etc.

To get started, you need to download and install the Eclipe plugin UML2 Tools in your Eclipse install.

Go to:
We are actually going to use the 0.9.1 Integration Builds plugin, simply because it is more stable, and has several key bug fixes.
Download the All-In-One Update Site and save the .zip file
In Eclipse, go to Help > Install New Software
Click Add
Enter the name UML2 Tools in Name
Click Archive and select the .zip file you downloaded.
1 . Click OK, and continue through the installation process

Once that process is complete, the Eclipse UML2 Tools plugin should now be installed and working.

To get DocBox to generate the .uml file that UML2Tools needs, we use the UMLstrategy. For example:

This will generate the .uml (in this case docbox.uml) file which we can then use.

To view and edit the UML diagrams from here:

Browse to the .uml file that you generated in the Navigator Pane
Right click on the .uml file
Select Initialise Class Diagram

You will now be presented with a UML Class diagram of your CFC model.

There are other types of UML2 diagrams that can be created. Have a look at the UML2 Tools documentation for more options.

There are some assumptions that are made by this strategy, when converting from CFCs to UML diagrams, as some meta data on CFCS are not provided and/or cannot be specified.

A property/field is determined for a class when a get and set function exist with the same name (or set and is for boolean values) and the argument type of the set function matches the return type of the get/is function.
The scope for the property/field is selected by highest level of exposure between the getÂ and set functions. I.e. if getFoo() is public, and setFoo() is private, then the property foo is marked as public.

Custom Output

Create your own custom output format by extending DocBox's strategy system.

🛠️ In addition to the mainstream output formats, you can extend DocBox's AbstractTemplateStrategy class to generate your own which implements the IStrategy class.

/**
 * Strategy Interface for DocBox Documentation Generation
 * <br>
 * This interface defines the contract that all DocBox documentation strategies must implement.
 * Strategies are responsible for generating documentation output in various formats (HTML, JSON, XMI, etc.)
 * from the component metadata collected by DocBox.
 * <br>
 * <small><em>Copyright 2015 Ortus Solutions, Corp <a href="www.ortussolutions.com">www.ortussolutions.com</a></em></small>
 */
interface {

	/**
	 * Execute the documentation generation strategy
	 *
	 * This method receives the complete metadata query from DocBox and is responsible for:
	 * - Processing the component metadata
	 * - Generating the appropriate output format
	 * - Writing files to the configured output location
	 *
	 * @metadata Query object containing all component metadata with columns:
	 *            - package: The package name
	 *            - name: The component name
	 *            - metadata: The complete component metadata structure
	 *            - type: The component type (component, interface, etc.)
	 *            - extends: The extended component name (if any)
	 *            - implements: The implemented interfaces (if any)
	 *
	 * @return The strategy instance for method chaining
	 */
	IStrategy function run( required query metadata );

}

Advanced

API Reference

Complete API reference for DocBox classes and methods

This page provides detailed API documentation for DocBox's core classes and methods.

The main entry point for DocBox documentation generation.

Creates a new DocBox instance with optional initial strategy.

Parameters:

strategy - (Optional) Strategy name ("HTML", "JSON", "XMI", "CommandBox") or instance

Troubleshooting

Common issues and solutions when using DocBox

This guide covers common issues you might encounter when using DocBox and their solutions.

🚨 Common Errors

"Output directory does not exist"

Error Message:

The output directory [/path/to/docs] does not exist

Cause: The specified output directory doesn't exist on the filesystem.

Solution: Create the output directory before running DocBox, or ensure that the path is correct. You can create it manually or programmatically:

// Option 1: Create the directory first
directoryCreate( expandPath( "/docs" ), true );

// Option 2: Use an existing directory
new docbox.DocBox()
    .addStrategy( "HTML", {
        outputDir: expandPath( "/existing/path" )
    } )
    .generate( source: "/src", mapping: "app" );

Missing Source Mappings (CLI)

Error Message:

❌ ERROR: No valid source mappings found.

Cause: The BoxLang CLI command wasn't provided with source directory information.

Solution: Ensure you provide either:

--source and --mapping together
One or more --mappings:<name>=<path> options
JSON array via --source

Cause: JavaScript error in HTML templates when filtering methods with missing properties.

Solution: This was fixed in DocBox 5.0. Update to the latest version:

Error Message:

Cause: The mapping specified doesn't match the actual package structure.

Solution: Ensure your mapping matches your component path structure:

Problem: Files are still being documented despite exclusion pattern.

Cause: Exclusion patterns are applied to relative file paths, not absolute paths.

Solution: Use patterns that match the relative path structure:

Problem: Generated docs show components but no methods/properties.

Cause: Components lack JavaDoc comments or metadata.

Solution: Add proper documentation to your components:

Problem: Generic type annotations like Array<User> not appearing in docs.

Cause: Using standard @returntype instead of @doc.type.

Solution: Use the @doc.type annotation:

Problem: Interface implementations not showing in documentation.

Cause: Engine-specific metadata format differences.

Solution: DocBox 5.0+ handles both formats automatically. If using older versions, update:

Problem: Dark mode preference resets on page reload.

Cause: Browser localStorage might be disabled or cleared.

Solution:

Check browser console for localStorage errors
Enable localStorage in browser settings
Clear site data and try again

Problem: Method search doesn't filter results.

Cause: JavaScript not loading or Alpine.js initialization issue.

Solution:

Check browser console for errors
Ensure you're using a modern browser (Chrome, Firefox, Edge, Safari)
Clear browser cache and reload
Check network tab for failed asset loads

Problem: Documentation appears unstyled or broken.

Cause: Asset paths incorrect or theme not specified properly.

Solution:

Error Message:

Cause: bx-docbox module not installed.

Solution:

Problem: DocBox runs out of memory when processing large projects.

Solution:

Increase JVM heap size

Process in smaller chunks:

Use more aggressive exclusion patterns:

Problem: Documentation generation appears to hang.

Cause: Processing too many files or infinite recursion in inheritance.

Solution:

Add verbose logging to see progress
Check for circular dependencies in your code
Exclude unnecessary directories
Run in smaller batches

Problem: Module loads but CLI command errors out.

Cause: Module registration issue or conflicts.

Solution:

Problem: Documentation differs between CFML and BoxLang engines.

Cause: BoxLang uses different metadata structure for some properties.

Solution: DocBox 5.0+ automatically handles both formats. If you're on an older version:

Problem: JSON files generated but contain no data.

Cause: Source directory or mapping incorrect.

Solution: Verify your paths and mappings:

Problem: XMI strategy throws errors.

Cause: Missing or invalid output file path.

Solution:

Add debugging output to your generation script:

Verify your component metadata is readable:

Ensure DocBox can write to the output directory:

If you're still experiencing issues:

Check Documentation:
Search Issues:
Community Forums:

When reporting issues, please include:

DocBox version (box info docbox or boxlang module:docbox --version)
CFML engine and version
Operating system

DocBox

Introduction

💻 System Requirements

🔢 Versioning

Release History

Version 5.0

Version 4.0

Version 3.0

Version 2.0

What's New With 4.1.0

What's New With 4.0.0

BREAKING

NEW

Contributing

Getting Started

Installation

🦤 BoxLang Module Installation (Recommended for CLI)

CommandBox Web Runtimes

BoxLang OS Runtime

BoxLang CLI Tool Examples

CommandBox Module

BoxLang CLI Tool

Annotating Your Code

💬 DocBox Comments

Output Formats

JSON Output

JSON Schema

UML Output

Custom Output

Advanced

API Reference

Introduction

💻 System Requirements

🔢 Versioning

Release History

Version 5.0

Version 4.0

Version 3.0

Version 2.0

📄 License

🔗 Important Links

💼 Professional Open Source

HONOR GOES TO GOD ABOVE ALL

What's New With 4.1.0

Added

Fixed

Contributing

What's New With 4.0.0

BREAKING

NEW

JSON Output

FIX

🔧 Send a Pull Request

✅ Testing DocBox

Custom Output

🚀 Instantiate DocBox

⚙️ Properties

📝 Generate Documentation

Installation

🦤 BoxLang Module Installation (Recommended for CLI)

CommandBox Web Runtimes

BoxLang OS Runtime

BoxLang CLI Tool Examples

CommandBox Module

Using DocBox in a CFML Application

Download

Mapping

UML Output

Strategy Assumptions

JSON Schema

BoxLang CLI Tool

Overview Summary

Package Summary

Class Documentation

📦 Installation

CommandBox Web Runtimes

BoxLang OS Runtime

🎯 Usage

⚙️ Required Options

📂 Source Options