From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 2723 invoked by alias); 15 Aug 2010 17:24:58 -0000 Received: (qmail 2714 invoked by uid 22791); 15 Aug 2010 17:24:57 -0000 X-SWARE-Spam-Status: No, hits=-1.9 required=5.0 tests=AWL,BAYES_00,T_RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from oarmail.oarcorp.com (HELO OARmail.OARCORP.com) (67.63.146.244) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Sun, 15 Aug 2010 17:24:52 +0000 Received: from localhost.localdomain (216.186.145.118) by OARmail.OARCORP.com (192.168.2.2) with Microsoft SMTP Server id 8.1.436.0; Sun, 15 Aug 2010 12:24:50 -0500 Message-ID: <4C6822E0.5020108@oarcorp.com> Date: Sun, 15 Aug 2010 19:47:00 -0000 From: Joel Sherrill User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.1.11) Gecko/20100720 Fedora/3.0.6-1.fc12 Thunderbird/3.0.6 MIME-Version: 1.0 To: Florian Weimer CC: Robert Dewar , 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> <8739ugs0na.fsf@mid.deneb.enyo.de> In-Reply-To: <8739ugs0na.fsf@mid.deneb.enyo.de> Content-Type: text/plain; charset="ISO-8859-1"; format=flowed Content-Transfer-Encoding: 7bit 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/msg00246.txt.bz2 On 08/15/2010 04:09 AM, Florian Weimer wrote: > * 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". > For RTEMS, that's what we try to do. There is a User's manual and the Doxygen generated 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. > > That's a matter of style and project code style enforcement. > 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.) > > So....? As a user, I don't care how you implemented it. Really, most of this is largely a matter of the markup and what is included in the generated documentation. RTEMS uses Doxygen for C which is probably not the ideal language for this. We have guidelines that the .h file always defines the interface with no details on the implementation. If there are things that are implementation specific you need to document, they go in the bodies and are marked as internal or whatever. This way you can easily generate "public view" documents from only the .h files and "augmented" versions with internal details if you do .h and bodies. RTEMS is a very old C project which predates Doxygen by years. But we believe in specs versus bodies, interfaces versus implementations, etc. It was easy to convert our comments into Doxygen format. http://www.rtems.org/onlinedocs/doxygen/cpukit/html/index.html So just because it is possible to do the markup and generation badly, doesn't mean it isn't possible to do a good job in any language which supports separate specs and bodies. > 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. > And that's unfortunate. :( --joel RTEMS