From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 23092 invoked by alias); 3 Aug 2010 00:51:24 -0000 Received: (qmail 23082 invoked by uid 22791); 3 Aug 2010 00:51:23 -0000 X-SWARE-Spam-Status: No, hits=-1.3 required=5.0 tests=AWL,BAYES_00,T_RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from ausc60ps301.us.dell.com (HELO ausc60ps301.us.dell.com) (143.166.148.206) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Tue, 03 Aug 2010 00:51:17 +0000 X-Loopcount0: from 10.152.240.141 Subject: Re: GFDL/GPL issues Mime-Version: 1.0 (Apple Message framework v1081) Content-Type: text/plain; charset=us-ascii From: Paul Koning In-Reply-To: <11008022317.AA08984@vlsi1.ultra.nyu.edu> Date: Tue, 03 Aug 2010 00:51:00 -0000 Cc: dnovillo@google.com, Joe.Buck@synopsys.com, ams@gnu.org, bkoz@redhat.com, dewar@adacore.com, gcc@gcc.gnu.org, iant@google.com, mark@codesourcery.com, richard.guenther@gmail.com, stevenb.gcc@gmail.com Content-Transfer-Encoding: quoted-printable Message-Id: References: <4BFC6EF0.4090908@codesourcery.com> <20100714172307.3687a9c4@shotwell> <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> <11008022317.AA08984@vlsi1.ultra.nyu.edu> To: kenner@vlsi1.ultra.nyu.edu (Richard Kenner) 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/msg00019.txt.bz2 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. >=20 > 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 v= astly better than some of its siblings, like gdbint.) But very little of i= t is generated and very little of what comes to mind as possible subject ma= tter is suitable for being generated. Even when things have been set up from the start for generating documentati= on (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