From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 7132 invoked by alias); 15 Aug 2010 16:07:23 -0000 Received: (qmail 7119 invoked by uid 22791); 15 Aug 2010 16:07:21 -0000 X-SWARE-Spam-Status: No, hits=-0.3 required=5.0 tests=AWL,BAYES_50 X-Spam-Check-By: sourceware.org Received: from eggs.gnu.org (HELO eggs.gnu.org) (140.186.70.92) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Sun, 15 Aug 2010 16:07:16 +0000 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OkZE8-0001pH-2G for gcc@gcc.gnu.org; Sun, 15 Aug 2010 05:10:01 -0400 Received: from ka.mail.enyo.de ([87.106.162.201]:35463) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OkZE7-0001p9-Pz for gcc@gcc.gnu.org; Sun, 15 Aug 2010 05:10:00 -0400 Received: from [172.17.135.4] (helo=deneb.enyo.de) by ka.mail.enyo.de with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) id 1OkZDN-0001eK-QK; Sun, 15 Aug 2010 11:09:13 +0200 Received: from fw by deneb.enyo.de with local (Exim 4.72) (envelope-from ) id 1OkZDN-0002i8-Gs; Sun, 15 Aug 2010 11:09:13 +0200 From: Florian Weimer To: Robert Dewar Cc: Richard Kenner , mark@codesourcery.com, Joe.Buck@synopsys.com, ams@gnu.org, bkoz@redhat.com, dnovillo@google.com, gcc@gcc.gnu.org, iant@google.com, richard.guenther@gmail.com, stevenb.gcc@gmail.com Subject: Re: GFDL/GPL issues References: <4BFC6EF0.4090908@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> <11008022335.AA09107@vlsi1.ultra.nyu.edu> <4C575891.1000106@codesourcery.com> <4C5863D6.5090808@adacore.com> <87r5i0s2ic.fsf@mid.deneb.enyo.de> <4C67A8CD.70205@adacore.com> Date: Sun, 15 Aug 2010 16:11:00 -0000 In-Reply-To: <4C67A8CD.70205@adacore.com> (Robert Dewar's message of "Sun, 15 Aug 2010 04:43:57 -0400") Message-ID: <8739ugs0na.fsf@mid.deneb.enyo.de> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-IsSubscribed: yes 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/msg00237.txt.bz2 * Robert Dewar: >> Duplication is how other GNU projects handle this. For instance, many >> Emacs Lisp functions are documented twice: once as a docstring in the >> source code (which is roughly equivalent to the comment-in-spec >> approach), and once in the Elisp reference (which is GFDLed). > > Well probably we can all agree that such duplication is undesirable, > unless it is automated, since documentation can get out of sync. There's a school of thought that claims that things need to be described at least twice, both formally and informally. I don't think these people mean "code and documentation", but rather "two forms of documentation". > In the case of the commented Ada specs, there is no point in duplicating > them in the Ada documentation, since they are accessible easily in an > appropriate form in the specs. This approach is far less useful for languages which haven't got separate spec files because it encourages programmers of client code to look at the implementation, potentially picking up implementation details. It encourages the documentation writer to accidentally refer to internals, too. I don't think it works at all for modern C++ code where the surface syntax of an API is an emerging property. (The API of foo's type ensures that "if (foo) { ...}" works as expected, but the exact language mechanism which achieves that is an implementation detail, so you can't really attach a docstring to it.) On the other hand, it is better to generate *some* free documentation, instead of assuming that programmers will turn to proprietary documentation which is freely available on the web.