Lee,
What about taking that one step further:
<!---@ Description: This is a very nice piece of code,
although it could really be a bit more elegant.
@ Author: Lee Borkman
@ Programmer: Frances Borkman
@ Attribute: -->[C_Room]: The unique ID of a room to be booked
@ Attribute: <--Rooms: A WDDX query of Rooms data
--->
Just a thought. I understand the need for a parsing token. Not using the "@"
in documentation descriptions might be worth the tradeoff.
Phil
-----Original Message-----
From: BORKMAN Lee [mailto:[EMAIL PROTECTED]]
Sent: Monday, August 28, 2000 9:09 PM
To: '[EMAIL PROTECTED]'
Subject: RE: FuseDoc specification
Okay all,
I can certainly see the benfit in containing multiple comments within a
single <!--- ---> pair. The problem, of course, is that you then need to
define another delimiter, and thus restrict what can be included in the
CommentContent. "*" is probably not a good idea, as has been pointed out.
"!---@" is pretty sensible, though not particularly elegant. Still, not
much can be done about that - HTML and CF comments are pretty ugly to start
with.
So, we start with a simple FuseDoc comment like this:
<!---@ Description: This is a very nice piece of code --->
That would still be legal, and should still be allowed at any point in the
code. NOW, we also allow additional comments to be added in the same
comment-block:
<!---@ Description: This is a very nice piece of code,
although it could really be a bit more elegant.
!---@ Author: Lee Borkman
!---@ Programmer: Frances Borkman
!---@ Attribute: -->[C_Room]: The unique ID of a room to be booked
!---@ Attribute: <--Rooms: A WDDX query of Rooms data
--->
Obviously, this saves a closing "--->" for every comment in the block, while
retaining the "!---@" opening delimiter characters.
A QUESTION. Is this really any more readable? I'm not sure. Nevertheless,
this format could be encompassed within the standard (or guideline), and
users would be free to use it if and when they please. I have a feeling
that I would still stick with one comment per block for my code, just for
simplicity's sake. Here is the one-comment-per-code version of the same
information:
<!---@ Description: This is a very nice piece of code,
although it could really be a bit more elegant. --->
<!---@ Author: Lee Borkman --->
<!---@ Programmer: Frances Borkman --->
<!---@ Attribute: -->[C_Room]: The unique ID of a room to be booked --->
<!---@ Attribute: <--Rooms: A WDDX query of Rooms data --->
You see, there are no worries about how to indent, whether to put the
opening and closing <!---@ and ---> on a separate line, etc. Still, all of
this can certainly be included in the guidelines, and can be parsed without
much problem. I'll see if I can amend and post a new parser later today,
Sydney-time ;-)
Thanks for all the input everyone,
Bye for now,
Lee Borkman
http://bjork.net ColdFusion tags by Bjork
-----Original Message-----
From: John Quarto-vonTivadar [mailto:[EMAIL PROTECTED]]
Sent: Tuesday, August 29, 2000 12:22 AM
To: [EMAIL PROTECTED]
Subject: Re: FuseDoc specification
Hi Phil,
I definitely agree that getting so many of the closing comment blocks out of
the documentation section is a good idea. The trick is that the string
"<!---*" is fairly easy to parse as unique to the docs section, whereas the
single "*" represents something that could easily be informational rather
than a token. And when combined with ":" the other nominal token there is
ample potential for a poorly written doc that does not parse right. BUT...if
the token that uniquely identifies each element of the doc is somehow
clearly defined, then you're right that there need be only one comment
section starter at the beginning and at the end. (This was the benefit of
Hal's idea of START FUSE and END FUSEDOC). All we really need is a unique
enough string to use for Start and End, and a unique enough string to use
for each comment section. It a very helpful to use combo's of symbols since
that reduces potential redundancy, esp when they are combined in ways that
their other meanings could not take (example JS's "/*" which obviously
don't occur together when each takes on its other meaning of
division/multiplication nor when "/" is used in an URL nor when "*" is used
as a wildcard)
That all being said, much of Lee's idea can remain intact as long as the
initial "<" is removed from the start of each line, since "!---@" is rare
enough and a start/end taglet has been notated as well. It also mean the
final "--->" can be removed from each of Lee's line, like you noted.
----- Original Message -----
From: "Hulsey, James Phillip" <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>
Sent: Monday, August 28, 2000 9:10 AM
Subject: RE: FuseDoc specification
> Lee,
> First off...my team likes your stuff. Keep it up!
>
> I'd like to get your comments on this. I admit that this is a detail.
> What do you, and anyone else that cares to comment, think about taking the
> CF comment tags out of the middle of documentation blocks? It's not a
> parsing problem and it does increase readability.
>
> <!---**
> * general description for the file.
> *
> * @Designer: Who Ever (e-mail)
> * @Programmer: Who Else (e-mail)
> * @Attributes: --> [directory]: An absolute directory (eg,
c:\cfdocs\)
> * @Attributes: <-- etc.....
> *--->
>
> Method used now:
>
> <!---@ Description: general description for the file. --->
> <!---@ Designer: Who Ever (e-mail) --->
> <!---@ Programmer: Who Else (e-mail) --->
> <!---@ Attributes: --> [directory]: An absolute directory (eg, c:\cfdocs\)
> --->
> <!---@ Attributes: <-- etc..... --->
>
> Phil Hulsey
>
> -----Original Message-----
> From: BORKMAN Lee [mailto:[EMAIL PROTECTED]]
> Sent: Sunday, August 27, 2000 7:56 PM
> To: '[EMAIL PROTECTED]'
> Subject: Re: FuseDoc specification
>
>
> Okay, I give in.
>
> Due to lack of interest on CF-Talk, let's keep this on the FuseBox list
for
> now. I still want to insist on a general syntax that is not
> FuseBox-specific.
>
> As for PDL, I must admit that I'm a bit of a fan. What I'm looking for,
> though, is a general documentation syntax that can be used for PDL's
> comment-first development, or PragmaticProgrammers' code-by-contract
> development, or any process that you happen to fancy. You could, for
> example, have comments like this:
>
> <!---@ PDL: Keep track of current number of resources --->
> <!---@ PDL: If another resource is available --->
> <!---@ PDL: Allocate a dialog box structure --->
> etc
> etc
> (example from Steve McConnell's Code Complete).
>
>
> This could be parsed out and displayed along with all your other <!---@
> comments.
>
> Just need some way to handle indenting, though I guess you could just put
> tabs in the CommentContent??
>
> Lee (Bjork) Borkman
> http://bjork.net ColdFusion Tags by Bjork
>
>
> --------------------------------------------------------------------------
--
> --
> 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.
> --------------------------------------------------------------------------
----
> 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.
----------------------------------------------------------------------------
--
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.
----------------------------------------------------------------------------
--
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.
------------------------------------------------------------------------------
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.
