List of Custom Annotations

There are several optional annotations that can be put on ColdFusion Components, their functions and their arguments to help ColdDoc determine certain things that ColdFusion doesn’t natively describe.

These are here to help aid in automating the documentation of your object model.

colddoc:abstract

This is an annotation that is placed on a ColdFusion Component declaration that tells ColdDoc that this CFC is deemed to be abstract, and therefore should be documented as such.

You can set this in the following ways: Tag Syntax:

<cfcomponent colddoc:abstract="true">
</cfcomponent>

Script Syntax:

/**
 * @colddoc:abstract="true"
 */
component { ... }

Annotation Effects

The following effects in documentation will occur when colddoc:abstract="true" on a CFC.

<tr>
  <td width="50%">
    Eclipse UML2 Tools<br />
  </td>
  
  <td width="50%">
    Class is declared <em>abstract</em> within the UML diagram
  </td>
</tr>   
</tbody>

Documentation Strategy	Effect
HTML API	Class declaration will read: public abstract class Foo

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

For example, if I have:

<cffunction name="getFooArray" access="private" returntype="array" output="false">
 <cfreturn instance.foo />
</cffunction>

<cffunction name="setFooArray" access="private" returntype="void" output="false">
 <cfargument name="foo" type="array" required="true"/>
 <cfset instance.foo = arguments.foo />
</cffunction>

Then there is no way to determine what the type of object or value that is stored in that array, or if that is even important. It is useful to be able to specify this in generated documentation, as then future developers will know what objects are expected within that array/struct.

Therefore the generic annotation can be used on the return type to show that we are using an array of com.Foo objects in this array.

<cffunction name="getFooArray" access="private" returntype="array" colddoc:generic="com.Foo" output="false">
 <cfreturn instance.foo />
</cffunction>

This tells ColdDoc that the return type is an array of objects of type com.Foo, and it can generate documentation based on this.

You can also list generic types, which is particularly useful for collections with key-value pairs. For example, if a struct argument uses a UUID as a key, and a string as the value, you could declare that as follows:

<cffunction name="setMyStuct" access="private" returntype="void" output="false">
   <cfargument name="myStruct" type="struct" required="true" colddoc:generic="uuid,string">
   <cfset instance.myStruct = arguments.myStruct />
</cffunction>  

It should be noted that the generic annotation can be applied to any function return type or argument declaration, so you can use it as you deem necessary.

Annotation Effects

The following effects in documentation will occur when colddoc:generic="Foo" on a CFC's function or argument declaration

  <td width="50%">
    <b>Effect<br /></b>
  </td>
</tr>

<tr>
  <td width="50%">
    HTML API<br />
  </td>
  
  <td width="50%">
    Return or argument type declarations will be documented as: <em>array&lt;Foo&gt;</em><br />And <em>Foo</em> will be linked to the class's documentation page.
  </td>
</tr>

<tr>
  <td width="50%">
    Eclipse UML2 Tools<br />
  </td>
  
  <td width="50%">
    If the generic type is a CFC type, an association will be defined in the UML between the CFC and the generic type.<br />
  </td>

Documentation Strategy