Blog

Documenting CFML with DocBox

Michael Born February 25, 2022

Spread the word

Michael Born

February 25, 2022

Spread the word


Share your thoughts

This blog post will teach you how to install and use DocBox to document your CFML components.

What Is DocBox?

DocBox is an open-source library from Ortus Solutions which parses your CFML and generates HTML documentation based on component metadata and comments called "docblocks".

DocBox has a companion CommandBox module for generating documentation from the CLI, as well as a standalone library for generating documentation from your web app, a task runner, or any CFML script.

Writing DocBlocks

A "docblock" is any comment beginning with an additional asterisk: /** info here */. Docblocks are used to document the purpose and usage of methods, and properties within a component, as well as the component itself.

Oh, and the best part about docblocks? They benefit your code even without installing or using DocBox!

To write a docblock, simply write a multiline comment with an extra asterisk in the opening tag:

/**
 * I add widgets to the WidgetFactory.
 */

Our docblocks can contain as many paragraphs of explanation as necessary:

/**
 * I add widgets to the WidgetFactory.
 * 
 * No seriously, call this method with a widget, and I'll take care of adding it for you.
 */

Docblocks can even contain HTML tags for formatting:

/**
 * I add widgets to the WidgetFactory.
 * 

* * WidgetFactory.addWidget( myWidget ) * */

In the resulting HTML documentation, this would look something like:

generated HTML documentation showing WidgetFactory code example

Component Docblocks

Documenting a component with DocBox will look something like this:

/**
 * Vehicle class for managing the `vehicle` table's ORM entity data.
 * 
 * @author Michael Born
 * @date 2022-02-15
 * @since 2.6.0
 */
component accessors="true" {
    // component properties and methods...
}

Notice the use of @author, @date and @since tags to offer additional context about the original component implementation.

Here's how that component docblock renders in the resulting HTML documentation:

generated HTML documentation showing Since, Date and Author of the component

Method DocBlocks

We can also use docblocks for documenting methods with DocBox. Here's an example of what that might look like:

/**
 * Detect file mime type and return `true` if file is an image.
 * This is a speedy replacement for ACF's `isImageFile()`, which can take 15 seconds to process a high-res image.
 *
 * @filePath Full path to existing file.
 * @throws FileNotFoundException if file does not exist.
 */
public boolean function isImageFile(
    required string filePath,
    boolean strict = true
){
    // check image mime
}

Notice how we document each method argument via @{argumentName}, and also document that the method @throws a particular exception type. DocBox will also determine the @return and @access documentation tags by introspecting the method - no additional typing required!

The output will look like:

HTML documentation showing isImageFile method documentation

Property DocBlocks

Here's a quick example of documenting a maxRows property on a fictitious SearchService.cfc component:

/** 
 * Define the max number of rows to return.
 * 
 * Use the `getMaxRows()` getter or `setMaxRows( 100 )` setter to read and write this value, respectively.
 * 
 * @deprecated deprecated in favor of setPagination({ maxRows : 10 })
 */
property
    name="maxRows"
    type="numeric"
    default="0";

With this docblock, DocBox will generate HTML documentation that looks something like this:

generated documentation showing property description, type and default

Supported DocBlock Tags

DocBox supports all of the following documentation tags:

TagExplanationUse On
@authorProvides information about the author, typically the author’s name, e-mail address, website information, and so on.Component, Interface, Method
@versionIndicates the version number.Component, Interface, Method
@sinceIndicate which version this item was addedComponent, Interface, Field, Method
@returnDescribe the method’s return value.Method
@throwsIndicates exceptions that are thrown by a method or constructor. You can add multiple @throws in a function declaration.Method
@deprecatedIndicates that the item is outdated and shouldn’t be used.Component, Interface, Field, Method

Besides these standard tags, DocBox supports custom tags. Simply put @tagName followed by a description, and DocBox will include these in the documentation as key/value pairs. A personal favorite of mine is @cite to cite Stack Overflow or another online code source.

/**
 * I am a helper component for various Math utilities
 * 
 * @cite https://stackoverflow.com/a/10021060
 */

On a component, this would look like:

example of using a custom tag on a component docblock

Generating Documentation

To parse our source code and generate browseable documentation with DocBox, we're going to use the the DocBox Commands module from the CommandBox CLI.

Note: You can also generate documentation from your CFML application or any CFML script using the DocBox library directly. Check out the DocBox Output guide if you want to go this route.

First, we need to install the DocBox Commands module in CommandBox:

box install commandbox-docbox

Next, we run docbox generate, passing the source and mapping of the directories we wish to document:

box docbox generate source=models mapping=pippinCF

If our code extends or implements any third-party library component, or if our source path includes third-party libraries such as coldbox or testbox, we'll want to exclude these directories from the documentation:

box docbox generate source=models mapping=pippinCF excludes=coldbox

This excludes property can take a regular expression (NOT a comma-separated list) for excluding multiple paths:

box docbox generate source=models mapping=pippinCF excludes=coldbox|testbox|modules

Now that we're done fine-tuning the documentation source files config, let's configure the output. We start by setting a strategy. A DocBox strategy is the output formatter that will run against our chosen set of source files. There are three strategies currently available in DocBox:

  • HTML - Generates human readable, browseable documentation similar to the Java docs
  • JSON - Generates machine-readable JSON documentation suitable for Elasticsearch or a database.
  • UML - Generates an XMI file which can be used by UML tools like StarUML to generate a UML diagram of your source code.

We'll stick with the HTML strategy for now:

box docbox generate source=models mapping=pippinCF excludes=coldbox|testbox|modules strategy=HTML

Next we need to configure the HTML strategy. There are only two strategy settings we need to configure: a "project title" a la top-level heading, and the location of the generated output:

box docbox generate source=models mapping=pippinCF excludes=coldbox|testbox|modules strategy=HTML strategy-projectTitle='PippinCF' strategy-outputDir=./docs

This is all the configuration we need to generate HTML documentation from the command line. Running this command will generate HTML documentation with a search function and a package summary that looks something like this:

pippinCF package documentation with a search field and a bulleted list of package components

Conclusion

In summary, DocBox is a low-effort, high-reward tool for documenting your application code. To learn more about integrating DocBox into your workflow, check out my CFCasts series on Using DocBox.

Add Your Comment

Recent Entries

ColdBox 7.2.0 Released

ColdBox 7.2.0 Released

ColdBox, a widely used development platform for ColdFusion (CFML), has unveiled version 7.2. Packed with compelling new features, bug fixes, and enhancements, this release is designed to empower developers by boosting productivity, refining scheduled task capabilities, and enhancing the overall reliability and efficiency of application development. This article will delve into the key highlights of ColdBox 7.2 and elucidate how these advancements can positively impact developers in their daily coding endeavors.

Luis Majano
Luis Majano
November 20, 2023
Into the Box 2023 Series on CFCast

Into the Box 2023 Series on CFCast

Excitement is in the air as we unleash the highly anticipated ITB 2023 series exclusively for our valued CFCast subscribers – and the best part? It's FREE for CFCast members! Now is the perfect time if you haven't joined the CFCast community yet. Plus, we've got an incredible End-of-Year deal that's too good to miss

Maria Jose Herrera
Maria Jose Herrera
November 20, 2023
Ortus Deals are Finally Here!

Ortus Deals are Finally Here!

The much-anticipated Ortus End-of-the-Year Sale has arrived, and it's time to elevate your development experience! Whether you're a seasoned developer, a tech enthusiast, or someone on the lookout for top-notch projects, Ortus has something special in store for you. Brace yourself for incredible discounts across a wide array of products and services, including Ortus annual events, books, cutting-edge services, and more.

Maria Jose Herrera
Maria Jose Herrera
November 15, 2023