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.
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-dataAlso 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
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
Properties also have comments and you can add @
blocks as well.
DocBox at the Function Level
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 |
---|---|
| Provides information about the author, typically the author’s name, e-mail address, website information, and so on. |
| Indicates the version number. |
| Used to indicate the version with which this class, field, or method was added. |
| Provides a description of a method’s return value. |
| Indicates exceptions that are thrown by a method or constructor. You can add multiple |
| Indicates that the class, field, or method is deprecated and shouldn’t be used. |
| Anything you like. That's right, DocBox will document any block pairs for you in a simple output manner. |
| Not implemented yet |
Custom DocBox Blocks
Here are some blocks that ONLY DocBox can read:
Tag | Explanation |
---|---|
| Used on components to demarcate them as abstract components. Please note that you can also use the |
| 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 |
Examples
All of the ortus repos have all their CFC documented. Please check out some of them here:
Last updated