Hi all,
Our old thread, "Documentation System for Cold Fusion", seems to have
wandered, as old threads are wont;-)
Perhaps we might start afresh. There seems to be some confusion about
proposed standards, etc, especially since Fred denies having any proposed
anything (I think).
Let me lay out the basic problem and requirements as I see them. It might
then be fruitful to discuss whether these are complete/correct, before we
proceed to discuss possible solutions. Please feel fee to slap me down if
this is tedious or abhorrent;-)
Here are the essentials that I propose for a general ColdFusion
source-documentation standard:
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.
QUESTION: ARE WE AGREED AS TO THESES ESSENTIALS? Disgree with any? Want to
add more?
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-cum-test-bench that can integrate documentation
display with other kinds of capability (eg, software metrics, unit testing).
So the overall plan:
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.
What do you all reckon???
Lee Borkman ([EMAIL PROTECTED])
http://bjork.net, ColdFusion Tags by Bjork
____________________________________________________________________
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.
