On Feb 13, 2008 1:18 AM, felix winkelmann <[EMAIL PROTECTED]> 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) _______________________________________________ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users