Okay,
I have been posting to FuseBox and CF-talk lists, because I think the topic is
about ColdFusion development, not just FuseBox. Unfortunately, only the
FuseBox lists members seem interested in the topic.
SO... I am making this brave move and posting ONLY to CF-Talk. I suggest that
we keep the discussion in that arena for now.
Once a general standard (I have no fear of this word) for ColdFusion is
proposed, then the FuseBox community can set about more specific FuseBox
documentation, hopefully within the general standard.
Now why the problem with the word "standard"? Surely a standard is just a
recommendation, a proposed language/vocabulary, designed to help us all
communicate clearly and with minimum fuss. Nobody is compelled to use it, but
if they do, then it should make people's live easier, ie LESS miserable. I
know what makes ME miserable... working on old code (mine or someone else's)
and having absolutely no idea what the hell is going on.
So to specifics (Hi Hal!), I propose the following for the GENERAL form of a
FusionDoc (not just FuseBox) comment:
<!---@ CommentType: CommentContent--->
As you can see, it's a normal CF comment, with an @ symbol immediately after
the <!---.
Then follows an optional CommentType (eg., Description, Attributes, Author,
Inputs and Ouputs, Crime and Punishment). Any characters are legal except ":"
and "--->".
A single ":" separates the Commenttype from the CommentContent.
The CommentContent may contain characters INCLUDING ":" and
line-feeds/carriage-returns, but excluding "--->".
I also propose that the CommentType can be ommitted:
<---@ this comment has not CommentType, but should still be parsed --->
The FusionDoc comments may appear anywhere in the code, in any order, although
the order should be significant (ie, retained by the parser). Multiple
comments with the same CommentType are permitted, and should be handled
sensibly by the parser.
So that's it for my FusionDocs proposal. It's basically just a way of
attaching particular comments to particular CommentTypes.
NEXT...
I have a second proposal, for a standard parser structure to contain the
parsed FusionDoc documentation:
A ColdFusion structure (ie, an Associative Array) of Arrays. The structure is
indexed by CommentType. Each constituent array is an array of strings,
containing the CommentContents (in order) of all related FusionDoc comments.
One other element of the structure is needed to maintain the order in whihc
the various CommentTypes appear. For this I currently use a list,
CommentOrderList, but I see that that limits the use of the list-delimiter
within the CommentType, so this should probably also be an array of strings.
You can test drive this approach by grabbing my SourceBrowser from
http://bjork.net.
Thanks all,
Lee Borkman
3rd World
____________________________________________________________________
Get free email and a permanent address at http://www.netaddress.com/?N=1
------------------------------------------------------------------------------
Archives: http://www.mail-archive.com/[email protected]/
To Unsubscribe visit
http://www.houseoffusion.com/index.cfm?sidebarRsts&bodyRsts/cf_talk or send a message
to [EMAIL PROTECTED] with 'unsubscribe' in the body.
