Contents > Developing ColdFusion MX Applications > Building and Using ColdFusion Components > Building ColdFusion components > Providing results Documenting CFCs

Documenting CFCs

ColdFusion provides several ways of including 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 method 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 Introspection: getting information about components.

The displayname and hint attributes

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

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

The hint attribute is intended for longer descriptions of the component, function, or argument. In the introspection display, it appears on a separate line or on several lines of the component or function 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. For example, in the following cffunction tag the Meta_TextType attribute is a metadata attribute. (The prefix Meta_ is not required, it is used here as a convention.) This attribute is not used as a function parameter; instead, it indicates that this method generates a form with a Text Area.

<cffunction name="makeForm" Meta_TextType="TextArea">

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

Metadata attributes are not useful just for documentation. Your application can use the GetMetadata function to get the metadata attributes and 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: Avoid using expressions in custom metadata attributes. Using expressions in metadata attributes can cause unpredictable behavior, because all metadata expressions are replaced by strings in the metadata structure returned from the GetMetadata function. Also, do not use the reserved attributes as your metadata attribute names. The reserved words for the cfcomponent tag are name, path, properties, functions, and extends. The reserved words for the cffunction tag are name, returnType, access, roles, output, and arguments. The reserved words for the cfargument tag are name, required, default, and type. The reserved words for the cfproperty tag are name and type.

The cfproperty tag

The cfproperty tag has several purposes:

• 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 of Using 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.

Contents > Developing ColdFusion MX Applications > Building and Using ColdFusion Components > Building ColdFusion components > Providing results Documenting CFCs

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | Bug Reporting

Version 6.1

Comments are no longer accepted for ColdFusion MX 6.1. ColdFusion 8 is the current version.

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/6.1/htmldocs/buildi43.htm

Add Comment