On Feb 12, 2008 10:13 AM, Tobia Conforto <[EMAIL PROTECTED]> 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...) _______________________________________________ Chicken-users mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/chicken-users
