Living in the UK means that some of use haven't been at work since Friday
(bank holiday - silly name but is a day off) and so haven't been a part of
this discussion.
Introduction
------------
I created cfdoc with the syntax it has for a reason, and I think that you
may have all missed (or just overlooked) the point. The syntax looks like
this:
=cfdoc
=endcfdoc
=head '<heading>'
=subhead '<subheading>'
=list
=endlist
=item
=b '<bold text>'
=br
=code
=endcode
It is readable.
It is parsable because you look for "=cfdoc" and "=endcfdoc" NOT "= cfdoc"
and "= endcfdoc". Please note the spaces which are similar to those between
the @ and the descriptive bit of text:
<!---@ Description: Blah! --->
Problems with this
------------------
Where does the Description end? Is it at the end of a line (not a good idea
IMHO). For things like that I used a delimiter of a single quote.
I agree that we should have all code in a single comment block and not in
lots of comment blocks. I like the idea of PDL to code before we start BUT
lets face facts, unless we come up with a standard (which is what I think we
are doing), people will not code in that way and so will not use the correct
documentation system.
Good parts of fusedoc
---------------------
I like the fusedoc ideas of having symbols for in and out variables etc, BUT
(IMHO) these are not immediately understandable (sorry Hal) and so people
are easily put off from using fusedoc.
Where do we go from here?
-------------------------
Lee's plan for building the doc structure is excellent (for those of you who
don't know!!!):
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.
People seem to be fixed on number 1 with using an updated version of
fusedoc. Fine, but I think it is still confusing and this could cause it
not to be taken up by a number of people (ie quite a lot of the CF Coding
profession).
Parsing the Document Syntax
---------------------------
If we are writing a syntax to be parsed, then we need the structure of the
syntax to be foolproof (and yes I do mean that some CF Coders are fools!).
It must not have spaces or any arbitrary structure that can be played with.
Proposal
--------
I propose changing Hal's syntax in some way to make it word and not symbol
based. I have no problem with using the general idea, BUT we do need a start
and end tag of some description. An example could be:
--> userID:
to
=in or @in
--> [userID]:
to
=in-opt or @in-opt
<-> userID:
to
=in-out or @in-out
etc.
Not complete and only a suggestion. Please don't tell me I'm fussing over
little things. The ability to parse and the simplicity to read these
documents is vitally important. It is also very important to be able to
pick up the syntax VERY quickly and easily.
I hope this makes sense.
Paul
PS I am still getting good feedback on cfdoc.
PPS If you got here, well done!
------------------------------------------------------------------------------
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.
