ColdDoc 1.0 Alpha

ColdDoc is a tool that has been built to generate documentation based on ColdFusion Component Meta Data.

There are several different documentation strategies that can be utilised with ColdDoc, and each produces a different type of documentation.

ColdDoc 1.0 Alpha

Installation
Requirements
ColdDoc API Documentation
Execution

HTML API Strategy
Eclipse UML2 Tools Strategy

Strategy Assumptions

PDF Strategy

Custom Annotations

colddoc:abstract

Annotation Effects

colddoc:generic

Annotation Effects

Applying Argument based annotations in CF9 Script

Not Implemented

Interface Support

Installation

ColdDoc needs to be installed in the web root of your ColdFusion application, or a mapping of colddoc needs to be set up for it.

Generally speaking, on a development server, it is convenient to set up a mapping, as then it can be used on any project on your ColdFusion server.

Requirements

ColdDoc is supported on ColdFusion 8+

ColdDoc API Documentation

ColdDoc API

Execution

When ColdDoc was first conceived, it's sole purpose was to general static HTML documentation based on Javadoc for CFCs. In this version things have changed a little.

ColdDoc now has a series of Documentation Template Strategies that can be used to generate a variety of documentation, including, but not limited to the original HTML Javadoc port.

This means that when using ColdDoc, you have to also instantiate the appropriate strategy that you want to use. This could be a strategy that comes bundled with ColdDoc, or possible a strategy of your own.

To generate documentation, first we instantiate Colddoc:

colddoc = createObject("component", "ColdDoc").init();

Next, we create some sort of Strategy for it to use, and set it as the strategy that ColdDoc will use to generate documentation:

strategy = createObject("component", "colddoc.strategy.api.HTMLAPIStrategy").init(expandPath("./docs"), "ColdDoc 1.0 Alpha");

colddoc.setStrategy(strategy);

From here, there are 2 ways in which we can invoke the generate() method on Colddoc:

If we only have a single directory with a single mapping, it can be done easily like so:

colddoc.generate(expandPath("/colddoc"), "colddoc");

Which passes into ColdDoc the absolute path to the mapping, and also the name of the mapping, and tells it to generate the documentation based on the CFCs it finds there.

If you have multiple mappings/directories that you want to be able to document with ColdDoc, you can simply pass an array of structs containing inputDir and inputMapping keys into ColdDoc's generate() method.

For example:

paths = [
    { inputDir = expandPath("/colddoc")
    ,inputMapping = "colddoc"
   }
    ,{
      inputDir = expandPath("com")
      ,inputMapping = "com"
    }
];

colddoc.generate(paths);

The reason we use an array of structs is because it is possible to have the same mapping in a system point to two different locations. I.e. there could be a server mapping that points to a directory, and a local directory with the same name, and they overlap. This gives the ability to be able to handle those situations.

HTML API Strategy

To create the static HTML documentation that ColdDoc originally started with, use the strategy colddoc.strategy.api.HTMLAPIStrategy, whose init() method takes the path to generate the HTML files in, and the title that you wish to use for your documentation.

Click here to see an example of HTML API output.

For example:

colddoc = createObject("component", "ColdDoc").init();

strategy = createObject("component", "colddoc.strategy.api.HTMLAPIStrategy").init(expandPath("./docs"), "ColdDoc 1.0 Alpha");
colddoc.setStrategy(strategy);

colddoc.generate(expandPath("/colddoc"), "colddoc");

This will generate the HTML documentation in expandPath("./docs") with the title "ColdDoc 1.0 Alpha".

Eclipse UML2 Tools Strategy

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.

Go to: http://www.eclipse.org/modeling/mdt/downloads/?showAll=1&hlbuild=I200907241018&project=uml2tools#I200907241018
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.
Download the All-In-One Update Site and save the .zip file
In Eclipse, go to Help > Install New Software
Click Add
Enter the name UML2 Tools in Name
Click Archive and select the .zip file you downloaded.
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 ColdDoc to generate the .uml file that UML2Tools needs, we use the strategy colddoc.strategy.uml2tools.XMIStrategy, which takes an init()

For example:
colddoc = createObject("component", "colddoc.ColdDoc").init();
strategy = createObject("component", "colddoc.strategy.uml2tools.XMIStrategy").init(expandPath("./uml/colddoc.uml"));
colddoc.setStrategy(strategy);

colddoc.generate(expandPath("/colddoc"), "colddoc");

This will generate the .uml (in this case colddoc.uml) file which we can then use.

To view and edit the UML diagrams from here:

Browse to the .uml file that you generated in the Navigator Pane
Right click on the .uml file
Select Initialise Class Diagram
Select the root package that you wish to model
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

PDF Strategy

A PDF Strategy is currently under development, and will be released in Alpha2

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.

Documentation Strategy	Effect
HTML API	Class declaration will read: public abstract class Foo
Eclipse UML2 Tools	Class is declared abstract within the UML diagram
PDF	Not Implemented Yet

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

Documentation Strategy	Effect
HTML API	Return or argument type declarations will be documented as: array<Foo> And Foo will be linked to the class's documentation page.
Eclipse UML2 Tools	If the generic type is a CFC type, an association will be defined in the UML between the CFC and the generic type.
PDF	Not Implemented Yet

Applying Argument based annotations in CF9 Script

Since ColdFusion 9 does not allow you to apply custom meta data to function arguments when writing in script syntax, ColdDoc parses the following meta data on a function the same as it would on arguments.

/**
* @argumentName.metadataname value of meta
*/

For example, if I wanted to set the use the custom annotation colddoc:generic on the argument myArray I could do the following:

/**
* Set myArray a value
* @myArray my Array
* @myArray.colddoc:generic string
*/
public function setMyArray(required array myArray) { ... }

Which would amount to the following in tag based sytax:

<cffunction name="setMyArray" access="private" returntype="void" output="false">
<cfargument name="myArray" type="array" required="true" colddoc:generic="string">

</cffunction>

Not Implemented

The following features are not implemented in ColdDoc:

Interface Support

CFInterface support has not been implemented in any of the strategies. This is mainly because I don't tend to use interfaces when programming ColdFusion.

That being said, I am more than happy to take patches to implement interfaces in any (or all) of the document strategies that ship with ColdDoc.