...
| Info | ||
|---|---|---|
| ||
CFEclipse IDE FarCry coding dictionaries: Installing the dictionary:
|
| Tip | ||
|---|---|---|
| ||
You can use the dictionary with CF Builder. Builder only accepts a single dictionary per version, so you will need to create a merged file of both CF? + FarCry xml files. Here is one I prepared earlier: |
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 | 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, and can contain HTML code. |
examples | Examples of tag usage. Will be used in HTML documentation, and can contain HTML code. |
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 /> |
bDocument | Must be set to true for the tag to be included in documentation |
bDeprecated | Set to true to indicate that use of this tag is discouraged. The description and examples should include further information about preferred usage. |
| Code Block |
|---|
<!--- @@hint: This does does stuff! @@single: false ---> |
...
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). To include an attribute that can't be CFParam'ed (e.g. attributes that are used in isDefined checks) you can comment out the CFParam tag defining the attribute, and include another comment immediately after it for comment variables.
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. |
...
| Code Block |
|---|
<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 --->
<!--- <cfparam name="attributes.backgroundcolor" default="none" /> ---><!--- Sets a background colour on the page --->
|
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.
...
Attribute | Description |
|---|---|
bDocument | A boolean value that indicates whether the component should be included in documentation. Defaults to false. |
bDeprecated | A boolean value that indicates whether the component is considered deprecated in favor of other code. Defaults to false. |
scopelocation | If the component is consistently available in one of the scopes, this attribute contains the path. |
...
Attribute | Description |
|---|---|
bDocument | A boolean value that indicates whether the function should be included in documentation. Defaults to false. |
bDeprecated | A boolean value that indicates whether the function is deprecated. Defaults to false. If true, information about the preferred code should be included in the description and examples. |
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 |
|---|
<cffunction name="getWebskins" bDocument="true" returntype="query" hint="Inspects the project directory structure and returns a query of all webskins">
...
</cffunction>
|
Comment variables:
Comment variables for functions can be added inside the function. A single comment immediately preceding the function is also checked.
Variable | Description |
|---|---|
description | A longer explanation of the function. Will be used in HTML documentation, and can contain HTML code. |
examples | Examples of function usage. Will be used in HTML documentation, and can contain HTML code. |
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. |
...
Components with a scopelocation defined, and their functions, are automatically added to the scope variables.
...