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:
Code guidelines
To ensure the documents are complete, the following guidelines should be followed when writing or updating code.
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.
Tags
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 --->
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 formats
CFEclipse Dictionary
- From the Docs tab, click CFEclipse Dictionary menu item. This will inspect the application code and generate the XML file.
- 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="farcry.xml" />
</version>
Current dictionaries: