Auto-documentation functionality is included in the FarCry Doc plugin. It generates documents based on actual code and inline comments. This plugin is only available to core developers – but we can all enjoy the results.

CFEclipse Dictionaries

CFEclipse IDE FarCry coding dictionaries:

Installing the dictionary:

This XML file should be saved in your CFEclipse application in the /plugins/org.cfeclipse.cfml_1.3.1.6/dictionary directory (or the equivilant for your version) as farcry.xml (or whatever you like).
Edit the dictionaryconfig.xml file in the same directory. Add your new dictionary the same way as the user.xml to the cf701 and cf8 coldfusion versions.

<version key="cf8" label="Coldfusion 8">
    <grammar location="cf8.xml" />
    <grammar location="user.xml" />
    <grammar location="farcry4.xml" />
    <grammar location="farcry5.xml" />
</version>

Documentation Guidelines

To ensure the documents are complete, the following guidelines should be followed when writing or updating code. By making sure all the relevant comments and metadata attributes are in place, we can automate the upkeep of various documentation sources.

Variable Comment

A comment variable is defined by putting "@@variablename:" followed by the variable value in a ColdFusion comment. A comment can contain as many of these variables as you like.

Tag Libraries

Basic Tag Information

Comment variables:

Variable	Description
hint	A short description of what the tag does. Used in CFEclipse as a tooltip.
description	A longer explanation of the tag. Will be used in HTML documentation. NOTE: to break a paragraph use a double line break.
single	A boolean value that indicates whether this is a single element tag (i.e. <abcd>) or not (i.e. <efgh>...</efgh>. Defaults to true.
xmlstyle	If this is a single tag, this boolean value indicates whether the tag needs to be used XML style, i.e. <abcd />


<!---
@@hint: This does does stuff!
@@single: false
--->

Attribute Information

Attribute information is extracted from CFParam'ed attribute variables. Comment variables should be included in a comment IMMEDIATELY after the CFParam tag (no spaces or line breaks).

CFParam attributes:

Attribute	Description
name	The attribute variable will be extracted as the tag attribute name
type	This will be extracted as the tag attribute type
default	This will be extracted as well. If it isn't defined, the tag attribute is flaged as required.

Comment variables:

Variable	Description
attrhint	A short explanation of the tag attribute. Used in CFEclipse as a tooltip
options	A list of the values supported by the attribute. Used in CFEclipse to provide a dropdown list of options.
returntype	If the tag attribute contains the name of a return variable, this should define the type of that variable. Not currently used.

If the comment doesn't contain any "@@" strings, the entire comment content is used as the hint.

<cfparam name="attributes.title" type="string" /><!--- The page title --->
<cfparam name="attributes.type" type="string" default="html" /><!--- @@attrhint: The output type. @@options: html,xml,pdf --->

Component Functions

All function information is extracted from the component metadata. This information is added to the component with attributes on the CFComponent, CFFunction, and CFArgument tags.

cfcomponent attributes

Attribute	Description
bDocument	A boolean value that indicates whether the component should be included in documentation. Defaults to false.
scopelocation	If the component is consistently available in one of the scopes, this attribute contains the path.

<cfcomponent name="security" bDocument="true" scopelocation="application.security">
    ...
</cfcomponent>

cffunction attributes

Attribute	Description
bDocument	A boolean value that indicates whether the function should be included in documentation. Defaults to false.
returntype	Defines the return type of the function. Defaults to void (i.e. no return)
hint	A short explanation of what the function does

<cffunction name="getWebskins" bDocument="true" returntype="query" hint="Inspects the project directory structure and returns a query of all webskins">
    ...
</cffunction>

cfargument attributes

Attribute	Description
name	The name of the argument
type	The type of the argument
required	Whether the argument is required
default	The default value
options	A list of the values supported by the argument. Used in CFEclipse to provide a dropdown list of options.
hint	A short explanation of the argument. Used in CFEclipse tooltips.

<cfargument name="package" type="string" required="true" options="farcry,security,resources,types,rules,formtools" hint="The package to inspect" />

Scope variables

Scope variables should be added to the /farcrydoc/packages/autodoc/scopes.cfm file in the FarCry Doc plugin in the form required for a CFEclipse Dictionary. Help information does not appear to be used by CFEclipse, but may be utilised for other documents.

<scope value="application.url.webroot" type="String"><help><![CDATA[
    The absolute root of the application. e.g. "", "/abcd"
]]></help></scope>

Components with a scopelocation defined and their functions are automatically added to the scope variables.

Document Generation

CFEclipse Dictionary

From the Docs tab (assumes you have access to farcydocs plugin), click CFEclipse Dictionary menu item. This will inspect the application code and generate the XML file.

Current dictionaries:

Auto-Documentation