> -----Original Message-----
> From: Sean Corfield [mailto:[EMAIL PROTECTED]
> Sent: Thursday, July 12, 2007 2:14 AM
> To: CF-Talk
> Subject: Re: SURVEY RESULTS: Is ColdFusion OO?
>
> On 7/11/07, Jaime Metcher <[EMAIL PROTECTED]> wrote:
> > Just musing about how to preserve some of the documentation benefits
> of
> > typing in the presence of duck-typing.
>
> Use the hint= attribute and readable argument names.
>
> I've seen various (repeated) suggestions to use custom attributes such
> as _type= and _returntype but I really don't see the point. The hint=
> attribute already shows up in the auto-generated documentation and
> lets you describe exactly what the argument / return value are about.
I think "hint" is great... but limited.
I've married metadata for my CFCs to a custom documentation tag - together
they really let them self-document. This tag lets you define things like
what exceptions a method throws, authorship and date information.
The tag is simple enough:
<dpDoc type="Revision"
name="Beta 0"
date="2005-03-18"
content="Initial Beta release." />
All attributes are optional and the contents of the "type" attribute are
made by convention, not design (in my CFCs I use Author, Version,
CreateDate, Overview, License, Plans, Revision, Return, Exception). The tag
could also be open for large, complex blocks of information (since it's not
a CF recognized tag we must wrap such instances in <cfsilent>).
The doc parser collects these tags and appends the content as arrays to the
metadata positionally (dpDoc tags that appear inside methods are appended to
the method's metadata for example).
Of course there are a thousand ways to do this (formatted comments, external
metadata, etc) but I find this way very easy, very extensible and very
compatible with the way I write CF.
For example here's some documentation generated completely from CF metadata
and dpDoc tags within the CFC. The doc parser also generates lineage
information and provides information about inherited properties and methods:
http://www.depressedpress.com/Content/Development/ColdFusion/DPLibraries/Doc
umentation/DocViewer.cfm?Component=cfc_DepressedPress.Framework.DP_Clickstre
am
The doc parser creates a superset of metadata+dpDocs and a second component
(the "viewer" in this case) creates an HTML representation of it.
Yes... I do love a nice set of documentation. ;^)
Jim Davis
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|
Create Web Applications With ColdFusion MX7 & Flex 2.
Build powerful, scalable RIAs. Free Trial
http://www.adobe.com/products/coldfusion/flex2/?sdid=RVJS
Archive:
http://www.houseoffusion.com/groups/CF-Talk/message.cfm/messageid:283538
Subscription: http://www.houseoffusion.com/groups/CF-Talk/subscribe.cfm
Unsubscribe: http://www.houseoffusion.com/cf_lists/unsubscribe.cfm?user=89.70.4
