On Aug 2, 2010, at 7:17 PM, Richard Kenner 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. Using
> tools to generate it from sources will DECREASE its quality, in my
> opinion. The best measure of quality of a document is how much time
> people spend writing and editing it.
I agree.
gcc and gccint docs are actually pretty reasonable. (Certainly gccint is
vastly better than some of its siblings, like gdbint.) But very little of it
is generated and very little of what comes to mind as possible subject matter
is suitable for being generated.
Even when things have been set up from the start for generating documentation
(like embedded documentation strings in Python code) such "documentation"
rarely captures more than trivial information about calling conventions.
Nothing of substance ever comes from documentation of that kind.
paul
