Adobe ColdFusion 8

Documenting CFCs

ColdFusion provides several ways to include documentation about your CFCs in your component definitions. The documentation is available when you use introspection to display information about the CFC or call the GetMetadata or GetComponentMetaData function to get the component's metadata. You can use the following tools for documenting CFCs:

  • The displayname and hint attributes
  • User-defined metadata attributes
  • The cfproperty tag

The following sections describe these tools. For information on displaying the information, see Using introspection to get information about components.

The displayname and hint attributes

The cfcomponent, cffunction, cfargument, and cfproperty tags have displayname and hint attributes.

The displayname attribute lets you provide a more descriptive name for a component, attribute, method, or property. When you use introspection, this attribute appears in parentheses next to the component or method name, or on the parameter information line.

You use the hint attribute for longer descriptions of the component, method, or argument. In the introspection display, this attribute appears on a separate line or on several lines of the component or method description, and at the end of the argument description.

Metadata attributes

You can include arbitrary metadata information as attributes of the cfcomponent, cffunction, cfargument, and cfproperty tags. To create a metadata attribute, specify the metadata attribute name and its value. For example, in the following cfcomponent tag, the Author attribute is a metadata attribute. This attribute is not used as a function parameter; instead, it indicates who wrote this CFC.

<cfcomponent name="makeForm" Author="Bean Lapin">

Metadata attributes are not used by ColdFusion for processing; they also do not appear in standard ColdFusion introspection displays; however, you can access and display them by using the GetMetaData or GetComponentMetaData function to get the metadata. Each attribute name is a key in the metadata structure of the CFC element.

Metadata attributes are used for more than documentation. Your application can use the GetMetadata function to get the metadata attributes for a component instance, or the GetComponentMetaData function to get the metadata for an interface or component that you have not yet instantiated. You can then act based on the values. For example, a mathCFC component might have the following cfcomponent tag:

<cfcomponent displayname="Math Functions" MetaType="Float">

In this case, a ColdFusion page with the following code sets the MetaTypeInfo variable to Float:

<cfobject component="mathCFC" name="MathFuncs">
<cfset MetaTypeInfo=GetMetadata(MathFuncs).MetaType>

Note: All metadata values are replaced by strings in the metadata structure returned from the GetMetadata function. Because of this, you should not use expressions in custom metadata attributes.

The cfproperty tag

The cfproperty tag is used to create complex data types with WSDL descriptors and for component property documentation, as follows:

  • It can create complex data types with WSDL descriptions for ColdFusion web services. For more information, see Using ColdFusion components to define data types for web services.
  • It can provide documentation of component properties in the ColdFusion introspection output. The introspection information includes the values of the standard cfproperty tag attributes.

Note: The cfproperty tag does not create a variable or assign it a value. It is used for information purposes only. You use a cfset tag, or CFScript assignment statement, to create the property and set its value.