This is great. It's nice to see everyone enthusiastically jumping on
something that will make all our lives easier!
Here's my 2 cents:
I like Hal's ideas. I also like Lee's extensible structure. However the
readability is a little more confusing than when using Java
documentation...from which, if I remember right, he got the idea.
Here's a clip from an Applet class method:
/**
* Determines if this applet is active. An applet is marked active
* just before its <code>start</code> method is called. It becomes
* inactive immediately after its <code>stop</code> method is called.
*
* @return <code>true</code> if the applet is active;
* <code>false</code> otherwise.
* @see java.applet.Applet#start()
* @see java.applet.Applet#stop()
* @since JDK1.0
*/
Maybe use something like this:
<!---**
* 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.....
*--->
or something similar to keep it as clean as possible?
Additional comments could be placed deep in the doc by using the same
syntax:
<!---**
* @Attributes --> [directory]: An absolute directory (eg, c:\cfdocs\)
* @Attributes <-- etc.....
*--->
Also, is there a agreed upon way to specify custom tags used similar to
included filed (+++)?
Again...just my 2 cents :)
Phil
-----Original Message-----
From: Lee Borkman [mailto:[EMAIL PROTECTED]]
Sent: Saturday, August 26, 2000 1:38 PM
To: [EMAIL PROTECTED]; [EMAIL PROTECTED]
Subject: Re: Documentation System for Cold Fusion
Yes,
Hal's original FuseDoc syntax has two main aspects:
1. The --> notation for attribute specification; and
2. The high-level FuseDoc header syntax, which codes Responsibilities,
Author, Attributes in a special order and manner.
Now I like part 1, the attributes specification notation very much. But I
don't think the overall FuseDoc header format is flexible enough to become
universal.
So I am proposing a more flexible high-level syntax, which is completely
compatible with Hal's attribute specification notation. For example, here
is
the "FusionDocs" header for one of my fuses:
<!---@ Description: Retrieves directory information into a query --->
<!---@ Designer: Lee Borkman ([EMAIL PROTECTED]) --->
<!---@ Programmer: Lee Borkman ([EMAIL PROTECTED]) --->
<!---@ Thanks: Uses Nate Weiss' QuerySort tag if available. Thanks Nate
--->
<!---@ Attributes:--> [directory]: An absolute directory (eg,
c:\cfdocs\)--->
<!---@ Attributes:--> [sortBy]: a SORT clause for the directory listing
(defaults to alpha) --->
<!---@ Attributes:--> [filter]: an optional file filter (eg, *.cfm) (not yet
implemented) --->
<!---@ Attributes:<-- CALLER.dir: a WDDX query of directory data --->
You can see that it's pretty much equivalent to one of Hal's FuseDoc
headers,
just as readable with some familiarity, and that it uses the same attribute
notation.
It is, however, easier to parse, and allows more flexibility in the number,
order and type of comment (eg, the Thanks to Nate). This can, of course,
easily be parsed into XML or WDDX, though my own parser currently builds a
CF
Structure of Arrays of Strings.
Keep up the goods work all,
Lee.
http://bjork.net
----------------
"John Quarto-vonTivadar" <[EMAIL PROTECTED]> wrote:
I liked the visually directional nature of Hal's suggested Fusedoc. (I think
the brackets one is more recent than the others,
tho, I don't recall it from the CFDJ article?).
I would suggestion simply using Lee's method of preceeding each line with
<!---@ (or somesuch) since it defines each individual element
and then Hal's directional "thingies" since they given further break down
info...it's almost the equivalent of:
<fusedoc>
<attributes type="variable" required="no" scope="ATTRIBUTES"
description="put user name here">UserName</attributes>
<attributes type="variable" required="yes" scope="APPLICATION"
description="PKID in DB">DSN</attributes>
<attributes type="file" stressedout="Jennifer"
callmethod="customtag">formula2attributes</attributes>
</fusedoc>
i think a melding of Lee and Hal's method accomplishes this and also lets us
convert to the quasi-XML above
-John
____________________________________________________________________
Get free email and a permanent address at http://www.netaddress.com/?N=1
----------------------------------------------------------------------------
--
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.
