This is the mail archive of the mailing list for the GCC project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: GFDL/GPL issues

Diego Novillo 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 am actually a bit dubious about automatic extraction of documentation from code. The kind of thing you can get this way is in any case easily obtained by browsing the code. All too often this kind of automatic generation is just a way of satisfying the need for quantity of documentation without enough attention to quality.

There are certainly exceptions to this, some of which have been
mentioned in this thread, but as a general mechanism, it is dangerous
in my opinion.

Ultimately the proper path to excellent documentation is to have
programmers who are as interested in generating documentation as
they are in writing code. If you don't have that, you will never
get really good documentation.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]