...
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.
...
| Info | ||||||||
|---|---|---|---|---|---|---|---|---|
| =
|
| }
||||||
CFEclipse IDE FarCry coding dictionaries: * [ Dictionary|^farcry4.xml] * [Farcry 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. |
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 | 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 |
...
/> |
...
| Code Block |
|---|
<!---
@@hint: This does does stuff!
@@single: false
--->
{code}
h3. Attribute information
Attribute information is extracted from |
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 |
|---|
<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 --->
{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} |
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 |
|---|
<cfcomponent name="security" bDocument="true" scopelocation="application.security">
...
</cfcomponent>
{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 |
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 |
|---|
<cffunction name="getWebskins" bDocument="true" returntype="query" hint="Inspects the project directory structure and returns a query of all webskins">
...
</cffunction>
{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 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 |
|---|
<cfargument name="package" type="string" required="true" options="farcry,security,resources,types,rules,formtools" hint="The package to inspect" />
{code}
h2. Scope variables
Scope variables should be added to the |
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 Block |
|---|
<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.
...
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.
...
| Code Block |
|---|
<version key="cf8" label="Coldfusion 8">
<grammar location="cf8.xml" />
<grammar location="user.xml" />
<grammar location="farcry.xml" />
</version>
{code}
|
Current
...
dictionaries:
...
...
...
...
...