From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 8698 invoked by alias); 3 Aug 2010 18:36:07 -0000 Received: (qmail 8688 invoked by uid 22791); 3 Aug 2010 18:36:06 -0000 X-SWARE-Spam-Status: No, hits=-2.1 required=5.0 tests=AWL,BAYES_00 X-Spam-Check-By: sourceware.org Received: from rock.gnat.com (HELO rock.gnat.com) (205.232.38.15) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Tue, 03 Aug 2010 18:35:28 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by filtered-rock.gnat.com (Postfix) with ESMTP id 5CA212BAB78; Tue, 3 Aug 2010 14:35:26 -0400 (EDT) Received: from rock.gnat.com ([127.0.0.1]) by localhost (rock.gnat.com [127.0.0.1]) (amavisd-new, port 10024) with LMTP id L6af1IoV6xF8; Tue, 3 Aug 2010 14:35:26 -0400 (EDT) Received: from [127.0.0.1] (nile.gnat.com [205.232.38.5]) by rock.gnat.com (Postfix) with ESMTP id C008C2BAC0C; Tue, 3 Aug 2010 14:35:12 -0400 (EDT) Message-ID: <4C586153.6000404@adacore.com> Date: Tue, 03 Aug 2010 18:36:00 -0000 From: Robert Dewar User-Agent: Thunderbird 2.0.0.24 (Windows/20100228) MIME-Version: 1.0 To: Diego Novillo CC: Mark Mitchell , Richard Kenner , iant@google.com, Joe.Buck@synopsys.com, ams@gnu.org, bkoz@redhat.com, gcc@gcc.gnu.org, richard.guenther@gmail.com, stevenb.gcc@gmail.com Subject: Re: GFDL/GPL issues References: <4BFC6EF0.4090908@codesourcery.com> <4C48D2C4.5000103@codesourcery.com> <4C48D60E.3000604@codesourcery.com> <20100726175013.20b12428@shotwell> <4C4E35B8.6010301@codesourcery.com> <4C4E37FC.1060208@adacore.com> <4C4F010C.5060401@codesourcery.com> <20100727180738.GU17485@synopsys.com> <4C4F20E8.5050206@codesourcery.com> <4C509E54.6090401@codesourcery.com> <11007291247.AA02219@vlsi1.ultra.nyu.edu> <4C5195FA.2060208@codesourcery.com> <4C52B176.7040807@adacore.com> <4C52E1C0.6090400@codesourcery.com> <4C53696B.7030801@adacore.com> <4C536B50.4010402@codesourcery.com> In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit Mailing-List: contact gcc-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-owner@gcc.gnu.org X-SW-Source: 2010-08/txt/msg00033.txt.bz2 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.