> 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.
Yes, but the audiences are different between users who read the manual and developers who read the code. For the best quality, the two descriptions may well be quite different, in emphasis, tone and other areas. If the emphasis is on finding text that's acceptable for BOTH purposes, you create documentation that's not ideal for EITHER. > 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. That's indeed a worthwhile goal, but doing it at the expense of the quality of the documentation is a very bad idea, in my opinion. The quality of documentation in the industry, and even in the Free Software community is pretty poor. GCC is known for a very high standard of documentation. Let's not lower it by substiting automated tools for quality handwritten documentation. I believe that tools have their purpose for such things as functions lists and detailed ABI documentation, but not in things like user manuals.
