I completely agree that the new fusedoc should include inline comments in
code. Another reason for this to be done would be to allow fusedoc to be
used in non-fusebox code, which is one of the reasons why I created CFDoc
(see postings a few weeks back for the debate if you missed it).
Please bear in mind that if you want a standard, you must create a standard
language for standard applications. By making it fusebox specific, there is
no way that non-fusebox people will understand it and so won't use it.
Making fusebox extensions to the language is fair enough, but lets start
from the basis of being a cold fusion documentation, not a fusebox
documentation (even though it's called fusedoc). Lets not allow it to
become a fringe documentation standard, but the CF documentation standard.
Paul
PS I am holding fire on moving away from CFDoc to fusedoc (mainly because
cfdoc works really nicely at the moment) but also because I am still sure it
has a place in the wider CF community, whereas fusedoc may not unless it
becomes more universal.
PPS In an environment like mine where I am working with other developers who
have there own style (not fusebox) of CF coding, fusedoc becomes quite
obsolete and completely unreadable, whereas cfdoc is perfectly acceptable
and readable (and very useful indeed).
> -----Original Message-----
> From: BORKMAN Lee [mailto:[EMAIL PROTECTED]]
> Sent: 26 September 2000 00:33
> To: Fusebox
> Subject: FuseDoc: New version being accepted?
>
>
> Hi all (Hal, Fred, everyone),
>
> I've been reading Hal's presentation on the emerging FuseDoc standard. It
> has changed somewhat, and has some clear advantages over the original
> version:
>
> 1. Allows user-definable CommentTypes
> 2. Is more readable
> 3. Allows flexible ordering within the FuseDoc block.
>
> My own FusionDoc syntax (eg., <---@ Description: This is a fuse --->) has
> gathered some interest, but not enough to be sustainable, I imagine.
>
> There is now only one major problem that I have with this FuseDoc emerging
> standard - the inability to embed FuseDocs comments WITHIN the code.
>
> That is not normally a problem, but there are two occasions when I really
> want to have the commments interspersed with the code:
>
> 1: Comment individual FuseActions. I like to comment my
> FuseActions at an
> early design phase, within the CFSWITCH. Whenever I add a new
> FuseAction, I
> include a new comment in the code. When the comments are parsed, I get a
> nice list of the legal FuseActions, and a brief description.
>
> 2: More generally, for a reasonably complex fuse, especially one that's
> going to be built by someone else, I like to sketch out the logic in PDL
> (hurray!!), using comments something like this:
>
> <---@ PDL: Get a list of users --->
> <---@ PDL: For each user --->
> <---@ PDL: +Get email address --->
> <---@ PDL: +If email is in Australia --->
> <---@ PDL: ++Build email --->
> <---@ PDL: ++Send email --->
> <---@ PDL: +End If --->
> <---@ PDL: Next user --->
>
> The code gets built in and around these comments. The FusionDoc parser
> grabs them from within the code, and a display module does sensible things
> with indenting to give a PDL description of the fuse logic.
>
>
> So, given that Hal's most recent FuseDoc syntax is widely accepted, does
> anyone else think that it can/should be extended to allow inline comments?
> Any thoughts?
>
> I will be publishing a new parser for Hal's FuseDoc syntax soon,
> that can be
> integrated into my SourceBrowser.
>
> Thanks everyone,
>
> bye for now,
> Lee Borkman
>
>
>
> ------------------------------------------------------------------
> ------------
> To Unsubscribe visit
> http://www.houseoffusion.com/index.cfm?sidebar=lists&body=lists/fu
sebox or send a message to [EMAIL PROTECTED] with
'unsubscribe' in the body.
------------------------------------------------------------------------------
To Unsubscribe visit
http://www.houseoffusion.com/index.cfm?sidebar=lists&body=lists/fusebox or send a
message to [EMAIL PROTECTED] with 'unsubscribe' in the body.
