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
Added
Adobe 2023 Testing and Support
New Github Actions
New supporting files
New build/Docs.cfc task for building the documentation using itself, before we where getting away with it because there was a previous DocBox version. Now we need to build the docs with the current version of DocBox.
Fixed
Build Versions and changelog
Removal of box.zip in root from old scripts
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
FIX
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!
Clone the repository fork to your machine - git clone [email protected]:ME/DocBox.git
Create a feature/ or patch/ branch: git checkout -b patch/syntax-error-in-html-output
Make your changes, commit as normal, and use git push to sync your commits to Github.
Please target all PRs at the development branch.
✅ Testing DocBox
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 to run the suite of DocBox tests.
Edit test specs in tests/specs as necessary, and run box testbox run again to validate tests pass.
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:
💻 System Requirements
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
BoxLang OS Runtime
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:
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
DocBox is professional open source software backed by Ortus Solutions, Corp offering services like:
🛠️ Custom Development
🎯 Professional Support & Mentoring
📖 Training
⚡ Server Tuning
🔒 Security Hardening
👀 Code Reviews
🚀
HONOR GOES TO GOD ABOVE ALL
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
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.
🚀 Instantiate DocBox
Begin by creating an instance of DocBox:
docbox = new DocBox();
⚙️ Properties
The following are the properties for this strategy:
projectTitle : Used in the top-level overview-summary.json file
outputDir : The output directory absolute path
Just pass them in the docbox.addStrategy() call:
📝 Generate Documentation
Now that you have an instance of DocBox configured with your strategy and its properties, just execute the generate() method with its appropriate arguments:
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 );
}
Package Navigation - Left sidebar with hierarchical tree
🚀 Instantiate DocBox
Begin by creating an instance of DocBox:
⚙️ Properties
The following are the properties for this strategy:
projectTitle : The HTML title used in the documentation
projectDescription : The HTML project description
outputDir : The output directory absolute path
Just pass them in the docbox.addStrategy() call:
🖄️ Using the Frames Theme
To use the traditional frameset layout:
📝 Generate Documentation
Now that you have an instance of DocBox configured with your strategy and its properties, just execute the generate() method with its appropriate arguments:
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.
Strategy Assumptions
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.
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.
📦 Installation
DocBox can be installed as a BoxLang core module using the bx-docbox slug:
CommandBox Web Runtimes
BoxLang OS Runtime
Once installed, the boxlang module:docbox command becomes available for generating documentation.
🎯 Usage
⚙️ Required Options
Option
Short
Description
📂 Source Options
Option
Description
⚙️ Additional Options
Option
Short
Description
💡 Examples
📌 Basic Usage
Generate documentation for a single source directory:
📌 With Project Title and Excludes
📌 Short Form Output Directory
📌 Multiple Source Mappings
Document multiple source directories with different mappings:
📌 Using Frames Theme
Generate documentation with the traditional frameset layout:
📌 JSON Array Format
Specify multiple sources using JSON array notation:
📌 Real-World Example: ColdBox Framework
🔧 Command Output
When you run the CLI tool, you'll see output like this:
🆘 Getting Help
Show Help
This displays comprehensive usage information including:
Command syntax
All available options
Multiple examples
Links to documentation
Show Version
Displays:
DocBox version
Author information
Website URL
⚠️ Common Issues
Missing Source Mappings
Error:
Solution: Ensure you provide either:
--source and --mapping together
One or more --mappings:<name>=<path> options
JSON array via --source
Missing Output Directory
Error:
Solution: Always specify where to generate documentation:
Source Directory Not Found
Warning:
Solution: Verify the source path exists and is accessible. Use absolute paths or paths relative to your current working directory.
🎨 Theme Selection
DocBox 5.0+ includes two modern themes:
Default Theme (Alpine.js SPA)
Features:
⚡ Alpine.js-based SPA
🌓 Dark mode support
🔍 Real-time search
📑 Method tabs
Frames Theme (Traditional)
Features:
🗂️ Traditional frameset layout
📚 jstree navigation
📱 Left sidebar for packages
🎯 Bootstrap 5 styling
🔗 Integration with Build Scripts
CommandBox Task Runner
Create a task.cfc to generate documentation:
Run with: box task run
CI/CD Pipeline
Add to your GitHub Actions, GitLab CI, or other CI/CD pipeline:
📚 Next Steps
- Learn about strategy properties and advanced configuration
- Explore HTML theme features
- Write effective JavaDoc comments
CommandBox Output
Generate CommandBox CLI command documentation with namespace organization
🎯 The CommandBox Strategy is a specialized output format designed specifically for documenting CommandBox CLI commands and namespaces. It extends the HTML API Strategy with CLI-focused terminology and navigation.
🚀 Overview
The CommandBox Strategy transforms CommandBox command components into searchable, navigable HTML documentation with command-specific features:
Command-Centric Navigation - Organizes by command namespaces (not packages)
CLI Terminology - Uses "commands" and "namespaces" instead of "classes" and "packages"
Qualified Names - Displays full command paths (e.g., server start, package show)
Namespace Hierarchy - Visualizes command organization and nesting
Frames Theme - Uses traditional frameset layout for CLI documentation
📦 Properties
The CommandBox Strategy accepts the following configuration properties:
Property
Type
Required
Description
🎯 Basic Usage
Using Strategy Alias
Using Full Class Path
📂 Generated Structure
The CommandBox Strategy generates the following file structure:
🎨 Features
Command Path Display
Unlike standard class documentation, CommandBox Strategy shows the full command path:
Namespace Organization
Commands are grouped by their namespace hierarchy:
server namespace
start command
stop command
CLI-Focused Templates
The strategy uses specialized templates that:
Display command syntax and usage
Show command examples in CLI format
Highlight command parameters and flags
Use CLI-appropriate terminology
📋 Real-World Examples
Documenting CommandBox Core
Generate documentation for CommandBox's built-in commands:
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:
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:
This guide covers common issues you might encounter when using DocBox and their solutions.
🚨 Common Errors
"Output directory does not exist"
Error Message:
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:
Missing Source Mappings (CLI)
Error Message:
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
"Cannot read properties of undefined (reading 'toLowerCase')"
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:
Class Not Found
Error Message:
Cause: The mapping specified doesn't match the actual package structure.
Solution: Ensure your mapping matches your component path structure:
Exclusion Pattern Not Working
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:
🔍 Metadata Issues
Empty Documentation Pages
Problem: Generated docs show components but no methods/properties.
Cause: Components lack JavaDoc comments or metadata.
Solution: Add proper documentation to your components:
Generic Types Not Showing
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:
Implements Not Detected
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:
🎨 HTML/UI Issues
Dark Mode Not Persisting
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
Search Not Working
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
Theme Not Loading
Problem: Documentation appears unstyled or broken.
Cause: Asset paths incorrect or theme not specified properly.
Solution:
🛠️ Build Issues
CLI Command Not Found
Error Message:
Cause: bx-docbox module not installed.
Solution:
Memory Issues with Large Codebases
Problem: DocBox runs out of memory when processing large projects.
Solution:
Increase JVM heap size
Process in smaller chunks:
Use more aggressive exclusion patterns:
Build Hangs or Takes Too Long
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
🦤 BoxLang-Specific Issues
BoxLang Module Not Loading
Problem: Module loads but CLI command errors out.
Cause: Module registration issue or conflicts.
Solution:
Metadata Format Differences
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:
📊 Strategy-Specific Issues
JSON Output Empty
Problem: JSON files generated but contain no data.
Cause: Source directory or mapping incorrect.
Solution: Verify your paths and mappings:
XMI/UML Strategy Fails
Problem: XMI strategy throws errors.
Cause: Missing or invalid output file path.
Solution:
🔧 Debug Tips
Enable Verbose Logging
Add debugging output to your generation script:
Check Component Metadata
Verify your component metadata is readable:
Validate Output Directory Permissions
Ensure DocBox can write to the output directory:
📞 Getting Help
If you're still experiencing issues:
Check Documentation:
Search Issues:
Community Forums:
📝 Reporting Bugs
When reporting issues, please include:
DocBox version (box info docbox or boxlang module:docbox --version)
CFML engine and version
Operating system
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 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.
These comments are commonly made up of two sections:
The output directory [/path/to/docs] does not exist
// 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" );
❌ ERROR: No valid source mappings found.
# Correct usage
boxlang module:docbox --source=/src --mapping=app --output-dir=/docs
# Or with mappings
boxlang module:docbox --mappings:app=/src --output-dir=/docs
box update docbox
Class [myapp.MyClass] not found
// If your component is at: /src/models/User.cfc
// And its component declaration is: component { }
// And you access it via: new models.User()
new docbox.DocBox()
.addStrategy( "HTML", { outputDir: "/docs" } )
.generate(
source = expandPath( "/src" ), // Source directory
mapping = "models" // Base mapping
);
/**
* User management service
*
* @author Your Name
*/
component {
/**
* Gets a user by ID
*
* @id The user ID
* @return User object or null
*/
public function getUser( required numeric id ) {
// implementation
}
}
/**
* Gets all active users
*
* @return Array of User objects
* @doc.type Array<User>
*/
public array function getUsers() {
return [];
}
Please note that BoxLang allows you to use both documentation annotation and code annotation styles.
/*** Hero is the main entity we'll be using to create awesome stuff** @author
/*** Hero is the main entity we'll be using to create awesome stuff** @author Captain America
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.
🎯 Property Annotating
/**
* Hero is the main entity we'll be using to create awesome stuff
*
* @author Captain America
*
*/
@name( "SuperHero" )
@transient
class{
/**
* A collection of aliases this superhero is known as
*/
property name="alias" type="array";
/**
* Internal alias name
*
* @deprecated true
*/
@propertyCodeAnnotation
@serialize( false )
property name="_alias" type="array";
}
/**
* Hero is the main entity we'll be using to create awesome stuff
*
* @author Captain America
*
*/
component name="SuperHero" accessors="true" transient{
/**
* A collection of aliases this superhero is known as
*/
property name="alias" type="array";
/**
* Internal alias name
* @deprecated true
*/
property name="_alias" type="array";
}
Properties also have comments and you can add @ blocks as well.
Function Annotations
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.
Argument Annotations
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.
Core Blocks
Here are some of the core blocks that can be used in DocBox:
Tag
Explanation
@author
Provides information about the author, typically the author’s name, e-mail address, website information, and so on.
@version
Indicates the version number.
@since
Used to indicate the version with which this class, field, or method was added.
Custom DocBox Blocks
Here are some blocks that ONLY DocBox can read:
Tag
Explanation
@doc.type
This is an annotation that can be placed on either a function or argument declaration. This annotation is used to specify what generic type is being used, which is particularly useful when a return or argument type is an array or a struct or any. The value can be a single type or a list.
🏷️ Custom Annotations
DocBox supports standard JavaDoc tags and recognizes custom annotations for enhanced documentation.
@doc.type
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:
Return Type Generics
Document arrays with specific element types:
Document structs with key/value types:
Parameter Type Generics
Document typed parameters:
Document complex struct parameters:
Inline Generic Annotations
BoxLang also supports inline doc.type attributes:
Complex Generic Types
For nested or complex types:
Best Practices for @doc.type
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
Complex Types: Break down complex nested types into multiple lines for clarity
/**
* This is a Javadoc compliant comment for DocBox
*/
/**
* get Java FileInputStream for resource bundle
*
* @rbFilePath path + filename for resource, including locale + .properties
*
* @return java.io.FileInputStream
*
* @throws ResourceBundle.InvalidBundlePath
*/
public function getResourceFileInputStream( required string rbFilePath ){
}
/**
* get Java FileInputStream for resource bundle
*
* @rbFilePath path + filename for resource, including locale + .properties
* @rbFilePath.deprecated true
*
* @return java.io.FileInputStream
* @throws ResourceBundle.InvalidBundlePath
*/
public function getResourceFileInputStream( required string rbFilePath ){
}
/**
* Get foo array
*
* @doc.type com.Foo
*/
private array function getFooArray(){
return variables.foo;
}
// Inline
private array function getFooArray() doc.type="com.Foo"{
return variables.foo;
}
/**
* Set my struct
*
* @myStruct.doc.type uuid,string
*/
private void function setMyStruct( required struct myStruct ){
instance.myStruct = arguments.myStruct;
}
// Inline
private void function setMyStruct(
required struct myStruct doc.type="uuid,string"
){
instance.myStruct = arguments.myStruct;
}
@doc.type TypeName
@doc.type KeyType,ValueType
/**
* Gets all active users from the database
*
* @return Array of User objects
* @doc.type Array<User>
*/
public array function getActiveUsers() {
return queryExecute( "SELECT * FROM users WHERE active = 1" )
.map( function( row ) {
return new User( row );
} );
}
/**
* Gets user preferences as a configuration map
*
* @return Struct mapping setting names to values
* @doc.type Struct<String,Any>
*/
public struct function getUserPreferences() {
return {
"theme": "dark",
"fontSize": 14,
"autoSave": true
};
}
/**
* Processes a batch of user records
*
* @users Array of User objects to process
* @users.doc.type Array<User>
*/
public void function processBatch( required array users ) {
for ( var user in arguments.users ) {
user.process();
}
}
/**
* Updates user settings with validation
*
* @settings Map of setting names to their values
* @settings.doc.type Struct<String,Any>
*/
public void function updateSettings( required struct settings ) {
validateSettings( arguments.settings );
saveSettings( arguments.settings );
}
// Return type with inline generic
public array function getUsers() doc.type="Array<User>" {
return entityLoad( "User" );
}
// Parameter with inline generic
public void function setCache(
required struct cache doc.type="String,Any"
) {
variables.cache = arguments.cache;
}
/**
* Gets a map of user IDs to their roles
*
* @return Map of numeric user IDs to arrays of role names
* @doc.type Struct<Numeric,Array<String>>
*/
public struct function getUserRoles() {
return {
1: [ "admin", "editor" ],
2: [ "viewer" ],
3: [ "editor", "contributor" ]
};
}
/**
* Gets a complex data structure for reporting
*
* @return Nested structure containing report data
* - Outer struct: Department name -> Department data
* - Department data: Struct with "users" (Array<User>) and "metrics" (Struct<String,Numeric>)
* @doc.type Struct<String,Struct>
*/
API Reference
Complete API reference for DocBox classes and methods
This page provides detailed API documentation for DocBox's core classes and methods.
📚 DocBox.cfc
The main entry point for DocBox documentation generation.
DocBox function init(
any strategy,
struct properties = {}
)
// No initial strategy
docbox = new docbox.DocBox();
// With strategy alias
docbox = new docbox.DocBox( strategy: "HTML", properties: {
outputDir: "/docs",
projectTitle: "My API"
} );
// With strategy instance
docbox = new docbox.DocBox(
strategy: new docbox.strategy.api.HTMLAPIStrategy(
outputDir: "/docs",
projectTitle: "My API"
)
);
DocBox function addStrategy(
required any strategy,
struct properties = {}
)
