Documenting ColdFusion Components

ColdFusion Components can be "introspected," meaning that they can be instructed to describe themselves. This documentation is made available in three ways:

• Formatted HTML documentation access by invoking the CFC via a URL, with no passed parameters (no query string)

• From within Dreamweaver MX

• Via WSDL (described in Chapter 32, "Web Services")

Via the tags used to create CFCs, ColdFusion can document method names, return code, arguments, inheritance, and more. All this is done automatically by ColdFusion, with no extra work from the developer.

However, to better document CFCs, ColdFusion allows developers to embed documentation information directly within CFCs. This documentation is ignored during regular processing, and is only used when documentation is generated. Additional documentation is specified using the optional hint attribute in the <cfcomponent>, <cffunction>, and <cfargument> tags.

The following snippet demonstrates the use of hint:

 <cfcomponent hint="All sorts of user processing">   <cffunction name="Get"               hint="Get user details">     <cfargument name="id"                 hint="User ID">     <cfset result="">     ...     <cfreturn result>   </cffunction> </cfcomponent> 

TIP

It's a good idea to use hint for every tag to improve the quality of your documentation. The extra effort is well worth it.