Re: [Chicken-users] Comprehensive documentation rewrite

[Elf]

On Wed, 13 Feb 2008, Shawn Rutledge wrote:
> <snip>
>
> All I'm hoping for as a starting point is a way to write parseable
> comments that can be converted into API docs.  The other stuff can be
> added later; a "be-all" documentation system cannot be expected to
> emerge fully formed either.  I will always think of separate
> documentation files as being fundamentally an adjunct... if you want
> to write a tutorial, sure it ought to be separate, but that's not
> where you start; you'd typically write it after the code.

im all for putting two lines giving the calling convention and a one-second
description above each procedure, macro, and variable.  im all for having
inline comments on difficult bits.  im all for putting a header giving some
basic data and a minichangelog.  thats where it ends for me, though.

i am not for generating full-fledged documentation in a variety of formats 
by doing comment parsing.  besides making the code infinitely harder to 
read and get around in, it restricts documentation to ONLY making sense for
programming objects.  meaning that when you start having to search for the 
code amidst the essays, theres a problem.  meaning that if you want to 
give some auxiliary info its not clear where it should go.  meaning that 
if all that docs were supposed to do was to give me an api ref, it would be
fine, but thats not reality.

even if we ignore that aspect, from a technical standpoint its REALLY 
obnoxious.  first, we have to handle everything as strings, to get it out of
the comments.  then we have to worry about parsing comments within comments
(ie, what happens if youre working on a section but dont want it to be out
but want to see how the rest is doing?).  then we have to worry about which
comment blocks are actual documentation vs inline comments (which is more 
trivial, but involves extra syntax).  plus, we dont get any of the advantages
of having a language capable of processing abstract nested syntax trees: we're
reduced to awk.

-elf