Fusedoc Specs

Fusedocs Convention

Symbol Key

Symbol	Description
Symbol	Template Called with <cfmodule>	Template Called with <cfinclude>
==>	Incoming variable, explicitly passed as an attribute by the calling template. This will always be an attributes-scope variable.	not applicable
<==	Outgoing variable, explicitly set in the calling template. This will always be a caller-scope variable.	not applicable
<=>	Indicates that the variable will be explicitly passed in and changed. Only applicable for structures.	not applicable
++>	A variable (form, url, request, cookie, session, client, application, or server) defined outside of the scope of the template that the template depends on.	A variable that the template depends on. This variable can be in any scope.
<++	A variable (form, url, request, cookie, session, client, application, or server) in a scope outside of the current template's scope that the template will create. Does not include the caller scope.	A variable (of any scope) that the template will create. It is imperative that all created variables are documented, since they may inadvertently affect variables in the calling template's scope.
<+>	A variable (form, url, request, cookie, session, client, application, or server) in a scope outside of the current template's scope that the template depends on and will change. Does not include the caller scope.	A variable (of any scope) that the template depends on and will change. It is imperative that all changed variables are documented, since doing so may inadvertently affect the calling template's scope.
+++	Code on which the template depends. The code my be CFML (called with <cfinclude> or <cfmodule>), JavaScript, a COM object, etc.
>>>	data file read by the template
<<<	data file changed or created by the template
xxx	data file deleted by the template
[varName]	For input variables, brackets indicate an argument that is optional. The default value should be indicated in the description field. For output variables, brackets indicate that the variable may or may not be set by the template. The description field should explain why the definition of the variable is conditional.
\|varName\|	Pipes around a variable indicate the value of the variable. This notation is useful for cases such as when a template creates a variable, but it doesn't know the name of the variable it is creating until runtime.

Requirements

Templates must include a "Description" section that describes in prose what the template does.
Templates must include a "Called With" section that lists how the template should be called. Valid values are "cfmodule", "cfinclude", and "HTTP".
Templates must include an "Interface" section that details all arguments and return values.
All variables listed in the Fusedoc stub must be scoped
The interface section must include a symbol, name, data type, and description for every argument/return value. Properties of created structures must be enumerated, but need not include a symbol.

Text Example

<cfsetting enablecfoutputonly="Yes">
<!--- ========================================================================================================================
|| BEGIN FUSEDOC || 

|| Properties ||

Title:  
Author: Web Q. Developer (webdeveloper@providence.org)

|| Responsibilities || 

The description of this template goes here. Write in the first person.

Called With: cfmodule | cfinclude

|| History ||

03/01/2001 WQD: template created

|| Attributes ||

         Name                                   Data Type         Description
         ----                                   ---------         -----------
   <+>   request.objects                        struct            structure that holds info about all the objects needed for this page request
   <++   request.objects.ADayInTheLife          struct            struct to create to contain properties for the object
            .id                                 string            unique id for this object
            .cfPathToDirectory                  string            absolute ColdFusion path to this object's root directory
            .cfPath                             string            absolute ColdFusion path to this object
            .urlToDirectory                     string            absolute url to this object's root directory
            .url                                string            absolute url to this object
            [.numStudents]                      integer           total number (1-based) of student for which this object can display information 
                                                                  (only defined if definePrivateProperties is true)
            [.defaultStudentNumber]             integer           student number to display when no student number is provided 
                                                                  (only defined if definePrivateProperties is true)
   ==>   [attributes.definePrivateProperties]   boolean           whether private properties should be defined (defaults to true)
   ==>   attributes.returnedRecordsetName       string            name of the recordset to create in the calling template's scope
   <==   caller.|returnedRecordsetName|         recordset         recordset containing something or other
   <==   caller.this                            struct            pointer to this request.objects.ADayInTheLife simply for shorthand use
   +++   act_foo.cfm                            CFML code         does something or other

|| END FUSEDOC || 
========================================================================================================================= --->
<cfsetting enablecfoutputonly="No">

XML Example

<cfsetting enablecfoutputonly="Yes">
<!--- ========================================================================================================================
<fusedoc fuse="act_Login.cfm" language="ColdFusion" specification="2.0">
 <responsibilities>
  I validate a user's login information.
 </responsibilities>
 <properties>
  <property name="Date" value="01 Jan 02" comments="Sample for book">
  <history author="Web Q. Developer" date="February 2, 2005" email="webdeveloper@providence.org" role="architect" type="create"/>
  <history author=" Web Q. Developer" date="March 18, 2005" email="webdeveloper@providence.org" role="developer" type="modify">
    Modified to do something that it didn't do before.
  </history>
 </properties>
<note>
  Notes can be used to capture information that doesn't have a specific Fusedoc element.
 </note>
<io>
  <in>
   <string name="XFA.onSuccess" optional="No" comments="Use if process succeeds">
   <string name="XFA.onFailure" optional="No" comments="Use if process fails">
   <string name="userID" optional="No">
   <string name="password" optional="No" comments="Hash() this string before comparing to password in database">
  </in>
  <out>
   <string name="userID" scope="client" oncondition="User is valid">
   <string name="firstName" scope="client" oncondition="User is valid">
   <string name="email" scope="client" oncondition="User is valid">
  </out>
 </io>
</fusedoc>
======================================================================================================================== --->
<cfsetting enablecfoutputonly="No">