chicken-users
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Chicken-users] Comprehensive documentation rewrite


From: Shawn Rutledge
Subject: Re: [Chicken-users] Comprehensive documentation rewrite
Date: Wed, 13 Feb 2008 11:32:52 -0700

On Feb 13, 2008 1:18 AM, felix winkelmann <address@hidden> wrote:
> In my experience separating the documentation from the code leads
> in the end to more consistent information. I've seen too much doxygen
> generated "documentation heaps" with no obvious start or beginning.

Well that's not the purpose... it's API documentation, not a tutorial.
 At my job for example we are required to write specs, but I still
like to have the structured comments and the generated documentation
from them.  The specs tend to be wrong or out-of-date unless you spend
extra days updating them.  Management thinks in terms of a waterfall
process:  you do design, then you code.  But when you code, you find
problems in the design, so it has to evolve.  Updating formal specs at
the same time makes the whole process slower, but I nearly always
manage to keep my in-code comments up-to-date.  And when I write
Scheme I sometimes write ordinary comments with at least a one-line
description of what the function does, and whatever constraints there
are on the parameters (if it's not obvious from the name of the
parameter).  I just wish those comments were parseable.

> Another effect is that documentation is structured to fit the doc-generating
> tool, instead of being easy to access for users.

It needs to be searchable.  Doxygen doesn't give you that because it
would involve some back-end code rather than just HTML.

> I happen to like svnwiki syntax. It's easy to use, non-obstructive and
> we have all the infrastructure to convert it into other formats.

Well the comments could be structured like that and the same parser
could be re-used to generate the HTML.  (Although personally as wiki's
go I'm partial to MediaWiki syntax.)

> Besides, all these doc overhauls just eat up developer time...

I would like to have some method of putting parseable comments in the
Scheme code.  Doesn't mean it has to replace other forms of
documentation... but isn't something like this available?  If the PLT
Scheme people are thinking about it, maybe we could borrow some code.

(OK I should look into it rather than just making suggestions... but I
can't promise how soon I will get around to it)




reply via email to

[Prev in Thread] Current Thread [Next in Thread]