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.)

DocBox reads component metadata and structured comments and outputs documentation in an HTML, JSON, or UML (diagram) format.

SYSTEM REQUIREMENTS

• Lucee 5+

• Adobe ColdFusion 2018+

Versioning

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

<major>.<minor>.<patch>

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

License

Apache 2 License: http://www.apache.org/licenses/LICENSE-2.0​

Important Links

• Code: https://github.com/ortus-solutions/docbox​

• Issues: https://ortussolutions.atlassian.net/jira/software/c/projects/DOCBOX/issues/

• Community: https://community.ortussolutions.com/

Professional Open Source

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

• Much More

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

Using DocBox in a Standalone Application

Installing and using DocBox consists of three main steps:

Download

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

Mapping

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:

In addition to the Docbox mapping, you will need a Coldfusion server mapping for each source code location. For example, documenting a component with implements="cbsecurity.interfaces.IAuthService" will require a mapping of cbsecurity to the installedcbsecurity source code so DocBox can find the referenced interface.

Using DocBox

The final step to get DocBox running is to write a CFML script that initializes, configures, and runs DocBox against your application code.

Using DocBox from the Command Line

1. Run box install commandbox-docbox to install the docbox command namespace

2. Run docbox help to get a list of commands

3. Run docbox generate help to show help for the docbox generate command

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 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.

DocBox reads your CFCs 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 CFC, 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: https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html

DocBox at the CFC Level

/**
* Hero is the main entity we'll be using to create awesome stuff
* 
* @author Captain America
* 
*/
component name="SuperHero" accessors="true" transient{
    // properties and functions
}

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.

DocBox at the Property Level

/**
* 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.

DocBox at the Function Level

/**
 * 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 ){
}

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.

cBox at the Function Level
/**
 * 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 ){
}

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:

Custom DocBox Blocks

Here are some blocks that ONLY DocBox can read:

/**
 * @doc_abstract true
 */
component doc_abstract="true" { ... }
component doc_abstract { ... }


/**
 * Get foo array
 * 
 * @doc_generic com.Foo
 */
private array function getFooArray(){
  return variables.foo;
}

// Inline
private array function getFooArray() doc_generic="com.Foo"{
  return variables.foo;
}

/**
 * Set my struct
 *
 * @myStruct.doc_generic uuid,string
 */
private void function setMyStruct( required struct myStruct ){
  instance.myStruct = arguments.myStruct;
}

// Inline
private void function setMyStruct( 
  required struct myStruct doc_generic="uuid,string" 
){
  instance.myStruct = arguments.myStruct;
}

Examples

All of the ortus repos have all their CFC documented. Please check out some of them here:

• https://github.com/Ortus-Solutions/DocBox

• https://github.com/coldbox/coldbox-platform

• https://github.com/Ortus-Solutions/commandbox

• https://github.com/Ortus-Solutions/ContentBox

The HTML API Strategy is used to create CFC documentation based on Javadoc. DocBox does not fully support all the Javadoc syntax, but hopefully it will soon.

Instantiate DocBox

Begin by creating an instance of DocBox:

docbox = new DocBox();

Properties

The following are the properties for this strategy:

• projectTitle : The HTML title used in the documentation

• outputDir : The output directory absolute path

Just pass them in the docbox.addStrategy() call:

docbox = new DocBox();
docbox.addStrategy( "HTML",
  {
      projectTitle = "My Docs",
      outputDir = expandPath( "/mydocs" )  
  } );

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:

docbox.generate(
    source  = "#expandPath( '/docbox' )",
    mapping = "coldbox",
    excludes = "tests"
);

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

Supported Output Formats

DocBox offers several built-in output formats as well as enabling you to create your own:

• HTML

• JSON

• UML

Each format is configured by its alias name, such as "JSON" or "HTML".

var docbox = new docbox.DocBox();
docbox.addStrategy( "UML", { outputFile : "./tmp/docs/app-diagram.uml" })

Backwards Compatibility

For backwards compatibility, specifying the full class path is still supported, as is specifying a single strategy when initializing DocBox:

variables.docbox = new docbox.DocBox(
  strategy = "docbox.strategy.uml2tools.XMIStrategy",
  properties={ 
    projectTitle = "DocBox Tests",
    outputFile   = variables.testOutputFile
  }
);

new docbox.DocBox()
    .addStrategy( "HTML", {
        projectTitle : "CommandBox",
        outputDir : expandPath( './docs' )
    } )
    .generate(
       source = expandPath( "/app" ),
       mapping = "app",
       excludes="(coldbox)"
    );

Generating Multiple Outputs

You can call the .addStrategy() method multiple times to specify multiple output formats:

new docbox.DocBox()
   .addStrategy( "HTML", {
      projectTitle="My Docs",
      outputDir="#expandPath( '/docs/html' )#"
   } )
   .addStrategy( "JSON", {
      projectTitle="My Docs",
      outputDir="#expandPath( '/docs/json' )#"
   } )
   .generate(
      source = expandPath( "/app" ),
      mapping = "app",
      excludes="(coldbox)"
   );

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:

docbox = new DocBox();
docbox.addStrategy( "JSON",
  {
      projectTitle = "DocBox API",
      outputDir = expandPath( "/resources/tmp" )  
  } );

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:

docbox.generate(
    source  = "#expandPath( '/docbox' )",
    mapping = "coldbox",
    excludes = "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

• Write a test

Send a Pull Request

• Fork DocBox or the DocBox documentation repo

• Clone the repository fork to your machine - git clone git@github.com: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:

1. After cloning the repo, run box install to install development dependencies

2. Run box start to boot a test server

3. Run box testbox run to run the suite of DocBox tests.

4. Edit test specs in tests/specs as necessary, and run box testbox run again to validate tests pass.

In addition to the mainstream output formats, you can extend DocBox's AbstractTemplateStrategy component to generate your own custom-formatted documentation:

component extends="docbox.strategy.AbstractTemplateStrategy" accessors="true"{
   /**
    * Generate JSON documentation
    * 
    * @metadata All component metadata, sourced from DocBox.
    */
   component function run( required query metadata ){
      // generate custom documentation format from arguments.metadata
   }
}

The JSON strategy outputs three types of files:

• Overview Summary

• Package Summary

• Class Documentation

Overview 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:

{
    "$id": "point-to-public-json-schema.json",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Package documentation index",
    "description": "This class index links to each generated class documentation JSON file.",
    "required": [],
    "type": "object",
    "properties": {
        "title": {
            "type": "string"
        },
        "classes": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "path": {
                        "type": "string"
                    }
                }
            }
        },
        "packages": {
            "type": "object",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "path": {
                        "type": "string"
                    }
                }
            }
        }
    }
}

See an example at JSONSchemaValidator.net

Package Summary

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:

{
    "$id": "point-to-public-json-schema.json",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Package documentation index",
    "description": "Index file documenting each coldfusion component inside a package level - i.e. per directory.",
    "required": [],
    "type": "object",
    "properties": {
        "title": {
            "type": "string"
        },
        "classes": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "path": {
                        "type": "string"
                    }
                }
            }
        }
    }
}

See an example at JSONSchemaValidator.net

Class Documentation

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:

{
    "$id": "point-to-public-json-schema.json",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Class documentation",
    "description": "Documents a single class in a ColdFusion package.",
    "required": [],
    "definitions": {
        "function" : {
            "type" : "object",
            "properties": {
                "name" : { "type" : "string" },
                "hint" : { "type" : "string" },
                "description" : { "type" : "string" },
                "access" : { "type" : "string" },
                "parameters" : {
                    "type" : "array",
                    "items": { "$ref" : "#/definitions/parameter" }
                },
                "returnType" : { "type" : "string" },
                "returnFormat" : { "type" : "string" },
                "position" : {
                    "type" : "object",
                    "properties" : {
                        "start" : { "type" : "integer" },
                        "end" : { "type" : "integer" }
                    }
                }
            }
        },
        "parameter" : {
            "type" : "object",
            "properties": {
                "type" : { "type" : "string" },
                "name" : { "type" : "string" },
                "required" : { "type" : "boolean" },
                "default" : { "type" : "string" }
            }
        }
    },
    "type": "object",
    "properties": {
        "name" : { "type": "string" },
        "package" : { "type": "string" },
        "type" : { "type": "string" },
        "extends" : { "type" : "string" },
        "implements" : { "type" : "string" },
        "hint" : { "type" : "string" },
        "description" : { "type" : "string" },
        "properties" : {
            "description" : "Literally the component properties set via `property` or `cfproperty`.",
            "type" : "object",
            "properties": {
                "type" : { "type" : "string" },
                "name" : { "type" : "string" },
                "access" : { "type" : "string" },
                "hint" : { "type" : "string" },
                "default" : { "type" : "string" },
                "required" : { "type" : "boolean" }
            }
        },
        "constructor" : { "$ref": "#/definitions/function" },
        "functions" : {
            "type" : "array",
            "items" : { "$ref": "#/definitions/function" }
        }
    }
  }

See an example at JSONSchemaValidator.net

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.

1. Go to: http://www.eclipse.org/modeling/mdt/downloads/?showAll=1&hlbuild=I200907241018&project=uml2tools

2. 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.

3. Download the All-In-One Update Site and save the .zip file

4. In Eclipse, go to Help > Install New Software

5. Click Add

6. Enter the name UML2 Tools in Name

7. 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:

docBox = new DocBox();
docBox.addStrategy( "UML", { projectFile = expandPath( "./uml/docbox.uml" ) });
docbox.generate( expandPath("/docbox"), "docbox" );

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:

1. Browse to the .uml file that you generated in the Navigator Pane

2. Right click on the .uml file

3. Select Initialise Class Diagram

4. Select the root package that you wish to model

5. Click OK

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.

• All associations are of type aggregation, rather than composition