Well,
I am very fond of Hal's specific syntax for documenting attributes (-->, <--,
++>, [], etc). Nicely pictorial, so easy to understand/write for developers
of various levels.
I am concerned, however, with how to embed this kind of documentation into a
more general doc format. Here are the essentials that I see:
1. Human readable/writable. Must be comprehensible to your most junior team
members.
2. Machine readable/writable. Must be able to be parsed or written by
machine, to allow development of future effort-saving software - browsers,
CASE tools, who-knows-what.
3. Expandable. Must allow the creation of new comment-types, which can be
tailored for use by individual organizations. Like HTML META tags. Take a
'core' set, but you can add your own if you desire.
4. Free Positioning. Can be placed anywhere in the source code, as
appropriate.
5. Applicable to ALL ColdFusion development, not just FuseBox.
Once a particular standard general syntax is basically agreed on, then we have
some other things to discuss, most importantly a standard core of comment
types (eg, Description, responsibilities, attributes-with-Hal's-syntax,
warning, author, designer, programmer, etc, etc, etc). Possibly a standard
dictionary of synonyms would also be handy.
After that, if we all begin to use the new syntax and core, we can look at
devising the associated paraphenalia:
1. A standard structure for holding parsed documentation (like a Structure of
Arrays of Strings);
2. An efficient parser to generate the above structure from standard code
3. Display modules for displaying the parsed structure in even-more-readble
form.
4. An expandable "browser" that can integrate documentation display with other
kinds of capability (eg, software metrics, unit testing).
So the plan as I see it:
1. Standard General doc syntax
2. Standard core of comment types
3. Standard parsed structure
4. Parser
5. Display Module
6. Integrated browser
7. World domination.
Perhaps we need to summarise the candidates for a General doc syntax, so we
can think about the first hurdle before worrying about which browser we
prefer?
Any thoughts?
Lee Borkman ([EMAIL PROTECTED])
http://bjork.net, ColdFusion Tags by Bjork
------------------------
"Hal Helms" <[EMAIL PROTECTED]> wrote:
But i LIKE to squat! And I do it so well. OK, I'm giving a talk on Fusedoc
at the upcoming Fusebox conference, so this is a good time to be talking
about this stuff. First, tell me what you DON'T like about the present
style. A quick refresher:
--> userID: NUMERIC, a primary key from USERS table
This indicates that an attribute will be explicitly passed into the fuse and
provides info on it
--> [userID]: NUMERIC, a primary key from USERS table
indicates an optional parameter
<-> userID: NUMERIC, a primary key from USERS table
indicates a "pass-thru" parameter, a var that is passed directly into AND
out of the fuse without change
++> application.userID: NUMERIC, a primary key from USERS table
indicates a global variable
+++ myFile.cfm
indicates an include file needed for this fuse to run
Each incoming symbol has an outgoing symbol for its counterpart so that
--> is matched with <--
and so forth. Here's what a real fusedoc looks like from a recent job I did:
<!-- CartSummary.cfm -->
<!-- [EMAIL PROTECTED] -->
<!---
|| Responsibilities: I show the user's cart summary based on the cookie
"cartID" that exists. If no cookie exists, I tell the user they don't have
anything in their cart.
||
--> RFA.continueShopping: a FUSEACTION
--> RFA.removeItemFromCart: a FUSEACTION
--> RFA.retotalCart: a FUSEACTION called when the Update_&partID&_&quantity&
is changed
--> RFA.checkout: a FUSEACTION
<-> fatherID: a STRING
<-> fatherType: a STRING ( Certification | Manufacturer | ProductLine |
HotDeals | searchString) default = Manufacturer
<-> fatherName: a STRING
<-- partID: PRIMARY KEY from Parts table on RFA.removeItemFromCart
@DeveloperNote: The ampersand indicates that this will be replaced by a
value at run time. For example, a valid variable name might be
"Update_2107_1"
<-- Update_&partID&_quantity: a NUMBER on RFA.retotalCart (may be multiple)
++> [cartID]: a COOKIE PRIMARY KEY from Carts table.
+++ qryGetCartSummary.cfm
+++ incHeader.cfm
+++ incFooter.cfm
||
END FUSEDOC--->
Now, the interesting thing about this job is that all the code for this job
was done overseas. Because of the time difference and the high cost of phone
calls, the only viable communication method we had was email. As it turned
out, almost no communication was required, as the coders understood how
Fusedoc worked and the fusestub contained all the info they needed to create
the code.
Can we improve on this? If so, I welcome ideas.
-----Original Message-----
From: John Foulds [mailto:[EMAIL PROTECTED]]
Sent: Friday, August 25, 2000 10:22 AM
To: [EMAIL PROTECTED]
Subject: Re: Documentation System for Cold Fusion
Not only too darn hard to read, too darn hard to write, not to mention
zero-tolerance in the parser.
The main thing is just that the notation be constructed so that it can be
read and parsed by a spider which can database it.
It's easy with XML because of it's strict notation. The challenge is to
come up with a syntax that walks the line between features/parsability and
easy authoring/viewing.
Does anyone have an address for the FuseDoc spec? I can't seem to find one
(Hal, quit squatting on fusedoc.org and fusedoc.com, and put something up
there). I would like to propose a few amendments.
John Foulds
Ottawa, Canada
----- Original Message -----
From: "McCollough, Alan" <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>
Sent: Friday, August 25, 2000 12:13 PM
Subject: RE: Documentation System for Cold Fusion
> Nah, I'll tell ya why I think so... The thing I like about FuseDoc is its
> simple enough where I can manually type in the fusedoc for a template with
> very little work. I've got a generic FuseDoc snippet stored in CF Studio,
> and I then fill in the blanks. FuseDoc as text is easily human readable.
> XML, WDDX, or other tagging schemes tend to have too much metadata in
> relation to the data. Too darn hard to read in Notepad or some other
> plain-text output.
>
> Its a balancing act between functionality and simplicity. But hey, doesn't
> every app we develop come under that principle?
>
> Alan McCollough
> Web Programmer
> Allaire Certified ColdFusion Developer
> Alaska Native Medical Center
>
> > -----Original Message-----
> > From: John Foulds [SMTP:[EMAIL PROTECTED]]
> > Sent: Friday, August 25, 2000 8:15 AM
> > To: [EMAIL PROTECTED]
> > Subject: Re: Documentation System for Cold Fusion
> >
> > Perhaps FuseDoc should just be XML, with an external DTD residing
> > somewhere
> > common.
> >
> > But it's not the lingo of the schema that matters, just making sure that
> > an
> > engine can read from it, and then parse the documentation in an
> > application's templates and drop the results into a DB where it can be
> > utilized by other documentation programs. ie:
> >
> > *a parent/child template browser
> > *a todo list (add FuseDoc element "Outstanding Items")
> > *a template description manual
> > *a query or variable dependency browser
> > *a change management viewer
> > *an author work history
> > *etc.
> >
> > p.s. packet? So Allarian.
> >
> > John Foulds
> > Ottawa, Canada
----------------------------------------------------------------------------
--
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.
____________________________________________________________________
Get free email and a permanent address at http://www.netaddress.com/?N=1
------------------------------------------------------------------------------
To Unsubscribe visit
http://www.houseoffusion.com/index.cfm?sidebarRsts&bodyRsts/fusebox or send a message
to [EMAIL PROTECTED] with 'unsubscribe' in the body.
