From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 7846 invoked by alias); 9 Aug 2013 23:28:54 -0000 Mailing-List: contact gdb-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sourceware.org Received: (qmail 7820 invoked by uid 89); 9 Aug 2013 23:28:54 -0000 X-Spam-SWARE-Status: No, score=-1.4 required=5.0 tests=AWL,BAYES_50,KHOP_THREADED,RCVD_IN_DNSWL_NONE,RCVD_IN_HOSTKARMA_YE,RDNS_NONE autolearn=no version=3.3.1 Received: from Unknown (HELO elasmtp-junco.atl.sa.earthlink.net) (209.86.89.63) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Fri, 09 Aug 2013 23:28:53 +0000 Received: from [68.96.200.16] (helo=macbook2.local) by elasmtp-junco.atl.sa.earthlink.net with esmtpa (Exim 4.67) (envelope-from ) id 1V7w6w-0008MQ-0s for gdb@sourceware.org; Fri, 09 Aug 2013 19:28:46 -0400 Message-ID: <52057B2D.3020400@earthlink.net> Date: Fri, 09 Aug 2013 23:28:00 -0000 From: Stan Shebs User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:17.0) Gecko/20130801 Thunderbird/17.0.8 MIME-Version: 1.0 To: gdb@sourceware.org Subject: Re: A new strategy for internals documentation References: <5201781A.3000607@earthlink.net> <83k3jyunt8.fsf@gnu.org> <5202A6D6.8090908@earthlink.net> <83li4ct7ot.fsf@gnu.org> <8361vfu9t4.fsf@gnu.org> <520423A2.6010304@earthlink.net> <201308090949.r799nMLL024338@glazunov.sibelius.xs4all.nl> In-Reply-To: <201308090949.r799nMLL024338@glazunov.sibelius.xs4all.nl> Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-ELNK-Trace: ae6f8838ff913eba0cc1426638a40ef67e972de0d01da940883c9696c878f628b43f1f59d8936619350badd9bab72f9c350badd9bab72f9c350badd9bab72f9c X-SW-Source: 2013-08/txt/msg00058.txt.bz2 On 8/9/13 2:49 AM, Mark Kettenis wrote: >> Date: Thu, 08 Aug 2013 16:02:58 -0700 >> From: Stan Shebs >> >> 4. Use Doxygen. >> >> Are you for or against, or indifferent? >> >> (For me Doxygen gets the nod by elimination, if nothing else. In the >> rather lengthy >> >> http://en.wikipedia.org/wiki/Comparison_of_documentation_generators >> >> there are not a lot of options that are portable, GPL, etc. LLVM's use >> of Doxygen, http://llvm.org/doxygen/index.html , seems pretty useful.) > > Yeah, that's a typical example of doxygen-generated documentation. > Lots of function prototypes, a few inheritance diagrams, and barely > any actual content. Not my defenition of useful. In fact I'm pretty > much conditioned such that my response to seeing doxygen generated > pages is to not ever bother reading it. > > Stan, I fear you're proposing a technical solution for a social > probleem. It does look that way :-) , but I'm not under any illusion that it will somehow magically change what people do. It does address a couple of the extant complaints, by expanding on the source-code commenting that is a well-established habit now, and by having good support for API specification. On the general subject of technical solutions changing social behavior, I will risk embarrassing myself by noting that I was long against moving GDB to a public repository, because I didn't think it was going to result in any more patches being contributed - after all, it was the same sources and the same approval process, so what difference did it make? I think I've been decisively proven wrong about that one! :-) Stan stan@codesourcery.com