Re: [Chicken-users] Comprehensive documentation rewrite

[Shawn Rutledge]

On Feb 12, 2008 10:13 AM, Tobia Conforto <address@hidden> wrote:
> My idea is to devise a "smart" document format, preferably s-expr
> based (maybe SSAX-based if nothing better comes to mind) and convert
> every piece of Chicken API documentation to that format: both for eggs
> and for the base system.  This includes any relevant SRFIs that are
> part of Chicken or of some eggs.

I like the idea of being able to put the documentation into the code;
something like Doxygen is needed for Scheme.  I think it's not the
first time such an idea has been proposed, but I don't know much about
what has been tried.

The trouble with systems like Doxygen and JavaDoc is having to parse
comments, which ordinarily are ignored.  And an S-expr method provides
some potential for other algorithmic purposes beyond the documentation
itself.  (Ideas will suggest themselves once the potential is there,
no doubt.)  There could start to be a coding standard/consensus just
as there is with JavaDoc and Doxygen, that you write a comment block
for every function, describing what it does, the parameters, etc.

The author of an egg is probably often the most qualified to write the
documentation; or else a close collaborator could write it (within the
code) and commit to Subversion, right?  So from one side the editable
wiki is handy for random users that see problems with the docs and can
quickly contribute the corrections, but from another, how many edits
are really being done there?  and it doesn't feel right to have the
documentation exist separate from the code.  Then it's more likely for
the two to be out-of-sync.

Maybe when someone edits the wiki, diffs could be sent to the author,
for later insertion into the next version of the egg.  But I think the
regular documentation should be inline with the code, because it helps
to encourage the good habit of keeping it up-to-date every time one
makes a change to the code.

(Sorry if I'm just stating the obvious...)