>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
I am for this approach 100% (Lee, you reposted as I was writing this).
First off, creating a documentation standard is phenomenal, and goes a long
way towards the original aim of Fusebox, which was interoperability of work
(man, such a long way since that thread long ago... it seems like just
yesterday).
>Perhaps we need to summarise the candidates for a General doc syntax...
That's a good start. I hope we can agree that whatever it is, it is still
called FuseDoc, and Hal still does the admin and maintains the web site for
it. :)
>Human readable/writable. Must be comprehensible to your most junior team
>members.
Perhaps I am dyslexic, but I am not convinced that the pictoglyphs are the
best method for documenting. I find them more difficult to read than text
or acronyms. If I was to put them in front of a junior, I think he/she
would choke.
I find the javadoc snippets Phillip posted more readable, because they are
more literal. It is after all documentation, not code.
* @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
* @Designer Who Ever (e-mail)
* @Programmer Who Else (e-mail)
* @Attributes --> [directory]: An absolute directory (eg, c:\cfdocs\)
* @Attributes <-- etc.....
I know, I know, it's easy to be a critic. I have some free time later in
the week, and am hoping to do some research and thinking on this.
Finding info on any/all of the mentioned syntaxes isn't a piece of cake.
Finding the FuseDoc stuff is tough enough alone. I will post in a moment
what I understand the FuseDoc syntax to be, hopefully Hal will take it and
laugh at it and correct it and put it up in some structured form (which he
probably has around anyways).
Today is the 26th. Perhaps a call for syntax logic, with a deadline of a
week or two. Anyone posting a syntax (or amendment to an existing one)
should describe their proposal in as much detail as they can.
If that can get a few people in agreement, someone put up a posting with a
subject line of something like *** CALL FOR FUSEDOC SYNTAX ***.
Then we will be able to evaluate the alternatives and move on to comment
types.
John Foulds
Ottawa, Canada (another 3rd world country, home of the 66 cent dollar)
----- Original Message -----
From: "Lee Borkman" <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>; <[EMAIL PROTECTED]>
Sent: Saturday, August 26, 2000 10:56 AM
Subject: RE: Documentation System for Cold Fusion
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
------------------------------------------------------------------------------
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.
