[CFCDev] Additional documentation attributes for CFC, CFArg, CFFunc

[John Temm]

Hi
In one system I have been working on, I have created a standard set of additional attributes that I place in all of my CFC tags to increase the granularity of the docs for the API.  I include these below for interest.  I am wondering if anyone else is doing something similar and if anyone has ideas for additional attributes or other ways of doing similar.  All these attrib's are accessible with getMetaData().
Cheers
Chip Temm
__________________________________

CFComponent

 

ClassID="" This is the unique identifier used to identify type in stored instance references. NOTE: This depends a lot on how you structure your app and your strategy for persisting your objects

DisplayName='{string}' This is a standard attribute in CF, but we mention it here to show that we use it to provide UI info when refering to instance info. For the StoredFile class, this is 'Download'

PluralDisplayName='{string}' The plural name of class instances. For the Person class, this is 'People'

abstractClass="{BOOLEAN}" Default=NO, so if this is undefined, assume NO. If this were Java, we would declare this class abstract because it never has instances

interfaceClass="{BOOLEAN}" Default=NO, so if this is undefined, assume NO. If this were Java, we would declare this class an interface because other classes implement its method signatures only

implements="{CLASSNAME}" If undefined, doesn't implement any other class interfaces. If this were Java, declaring that this class implement s another would enforce the existence in this class of methods in the interface class. Here it cannot be enforced, but it gives a hint to developers what they can expect of this class.

version="{NUMERIC}" Classes can be versioned so that developers can keep track of what is happening in the API.  You could write notifiers to email developers who put watches on specific classes

changelog="{STRING}" Developers should track their changes to classes here in the format:

		____________________________________
			14 May 2003 13:21:33 {DATE}
			Chip Temm {DEVELOPER}
			Created. {NOTES}
		____________________________________
	

CFProperty

displayname="{STRING}" can be tapped into for UI code generation. The UI name for the property.

hint="{STRING}" explain for developers what this property holds if displayname is not enough

CFFunction

staticMethod="{BOOLEAN}" If this were Java, would we declare this method static because it doesn't act on an instantiated object

interfaceMethod="{BOOLEAN}" If this were Java, would we declare this an interface method because it must be implemented in classes that implement this class

usage="{STRING}" Information for developers.

throws="{STRING}" Comma delimted list of exceptions that may be thrown by the method.

version="{NUMERIC}" Methods can be versioned within the Class so that developers can keep track of what is happening in a given method: You can have version numbers for the Class and for each of its methods

category="{STRING}" What category the function falls under. E.g., 'security', 'data access', 'util' .  Tracking different aspects of functionality

changelog="{STRING}" Developers should track their changes to methods here in the format:

		____________________________________
			14 May 2003 13:21:33 {DATE}
			Chip Temm {DEVELOPER}
			Created. {NOTES}
		____________________________________
	

deprecated="{BOOLEAN}" When true, the method is deprecated in the current version. This implies that it will not be supported in future versions.

seeAlso="{STRING:packageName.classname.functionName}" See a related function. Unqualified names indicate function in the same class. For qualified names, the final token is the function name.

CFArgument

hint="{STRING}" explain for developers what this argument means

allowedvalues="{LIST}" a list of values that the method will accept for this argument. Methods with arguments having this attribute will implement some internal method of restricting input to the allowed values and will throw an AllowedValueException if input does not conform.

deprecated="{BOOLEAN}" When true, the argument is deprecated in the current version. This usually implies that its value is ignored when processing the method.