Annotating Your Code

DocBox
Search…
Introduction
Getting Started
Output Formats
Annotating Your Code
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.
1
/**
2
 * This is a Javadoc compliant comment for DocBox
3
 */
Copied!
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 JavDoc spec click here: https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html​
DocBox at the CFC Level
1
/**
2
* Hero is the main entity we'll be using to create awesome stuff
3
* 
4
* @author Captain America
5
* 
6
*/
7
component name="SuperHero" accessors="true" transient{
8
    // properties and functions
9
}
Copied!
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
1
/**
2
* Hero is the main entity we'll be using to create awesome stuff
3
* 
4
* @author Captain America
5
* 
6
*/
7
component name="SuperHero" accessors="true" transient{
8
    
9
    /**
10
     * A collection of aliases this superhero is known as
11
     */
12
    property name="alias" type="array";
13
    
14
    /**
15
     * Internal alias name
16
     * @deprecated true
17
     */
18
    property name="_alias" type="array";
19
}
Copied!
Properties also have comments and you can add @ blocks as well. 
DocBox at the Function Level
1
/**
2
 * get Java FileInputStream for resource bundle
3
 *
4
 * @rbFilePath path + filename for resource, including locale + .properties
5
 *
6
 * @return java.io.FileInputStream
7
 * @throws ResourceBundle.InvalidBundlePath
8
 */
9
public function getResourceFileInputStream( required string rbFilePath ){
10
}
Copied!
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.
1
cBox at the Function Level
2
/**
3
 * get Java FileInputStream for resource bundle
4
 *
5
 * @rbFilePath path + filename for resource, including locale + .properties
6
 * @rbFilePath.deprecated true
7
 *
8
 * @return java.io.FileInputStream
9
 * @throws ResourceBundle.InvalidBundlePath
10
 */
11
public function getResourceFileInputStream( required string rbFilePath ){
12
}
Copied!
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.
@return
Provides a description of a method’s return value.
@throws
Indicates exceptions that are thrown by a method or
 constructor. You can add multiple @throws in a function declaration.
@deprecated
Indicates that the class, field, or method is deprecated and
 shouldn’t be used.
@{anything}
Anything you like. That's right, DocBox will document any block pairs for you in a simple output manner.
@see
Not implemented yet
Custom DocBox Blocks
Here are some blocks that ONLY DocBox can read:
Tag
Explanation
@doc_abstract
Used on components to demarcate them as abstract components. Please note that you can also use the abstract attribute that ColdFusion 2016+ introduced. 
@doc_generic
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.
1
/**
2
 * @doc_abstract true
3
 */
4
component doc_abstract="true" { ... }
5
component doc_abstract { ... }
6
​
7
​
8
/**
9
 * Get foo array
10
 * 
11
 * @doc_generic com.Foo
12
 */
13
private array function getFooArray(){
14
  return variables.foo;
15
}
16
​
17
// Inline
18
private array function getFooArray() doc_generic="com.Foo"{
19
  return variables.foo;
20
}
21
​
22
/**
23
 * Set my struct
24
 *
25
 * @myStruct.doc_generic uuid,string
26
 */
27
private void function setMyStruct( required struct myStruct ){
28
  instance.myStruct = arguments.myStruct;
29
}
30
​
31
// Inline
32
private void function setMyStruct( 
33
  required struct myStruct doc_generic="uuid,string" 
34
){
35
  instance.myStruct = arguments.myStruct;
36
}
Copied!
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​
​
Getting Started - Previous
Configuration
Next - Output Formats
HTML Output
Last modified 1yr ago
Copy link
Edit on GitHub
Contents
DocBox Comments
DocBox at the CFC Level
DocBox at the Property Level
DocBox at the Function Level