On Tue, Aug 3, 2010 at 1:17 AM, Richard Kenner <ken...@vlsi1.ultra.nyu.edu> wrote: >> We are already having trouble keeping our documentation up-to-date. >> Some of it is in such a poor shape as to be laughable. Yes, it's >> mostly our fault, but if we were able to generate documentation by >> simply extracting it from the code. Tools exist for this, and >> properly maintained, they are very useful. > > I disagree and think that's backwards. To get good quality > documentation, we have to WRITE good quality documentation.
That is true, but very often the documentation is needed in two places: in the code and in the manual. Especially for things like machine constraints, flags and options. And even if the documentation isn't needed in two places to, well, document something, it may still be useful to automatically generate parts of manual to avoid divergence between the manual and the compiler. But as it is, the good quality documentation cannot be written in the code... Ciao! Steven
