| Wiki Markup |
|---|
Auto-documentation functionality is included in the FarCry Doc plugin. It generates documents based on actual code and inline comments |
...
Code guidelines
To ensure the documents are complete, the following guidelines should be followed when writing or updating code.
| Info |
|---|
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
...
. This plugin is only available to core developers -- but we can all enjoy the results. {info|title=CFEclipse Dictionaries} CFEclipse IDE FarCry coding dictionaries: * [Farcry 4.x Dictionary|^farcry4.xml] * [Farcry 5.0 Dictionary|^farcry5.xml] {info} h1. Code guidelines To ensure the documents are complete, the following guidelines should be followed when writing or updating code. {info}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. {info} h2. Tags h3. 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
...
| | xmlstyle | If this is a single tag, this boolean value indicates whether the tag needs to be used XML style, i.e. <abcd /> |
...
| Code Block |
|---|
|
{code}
<!---
@@hint: This does does stuff!
@@single: false
--->
|
Attribute information
...
{code} h3. 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.
| Code Block |
|---|
|| 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.
{code}
<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. |
| Code Block |
|---|
{code}
h2. 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.
h3. 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. |
{code}
<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
...
{code} h3. 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
| Code Block |
|---|
|
| hint | A short explanation of what the function does |
{code}
<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. |
| Code Block |
|---|
{code} h3. 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. | {code} <cfargument name="package" type="string" required="true" options="farcry,security,resources,types,rules,formtools" hint="The package to inspect" /> |
Scope variables
...
{code} h2. 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. |
...
{code |
} <scope value="application.url.webroot" type="String"><help><![CDATA[ The absolute root of the application. e.g. "", "/abcd" ]]></help></scope> {code} Components with a scopelocation defined and their functions are automatically added to the scope variables. h1. |
...
Document |
...
CFEclipse Dictionary
...
formats h2. 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. |
...
{code |
} <version key="cf8" label="Coldfusion 8"> <grammar location="cf8.xml" /> <grammar location="user.xml" /> <grammar location="farcry.xml" /> </version> {code} Current dictionaries: |
...
* [Farcry 4.x |
...
Dictionary|^farcry4.xml] * [Farcry 5.0 Dictionary|^farcry5.xml] |