From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 22947 invoked by alias); 11 Feb 2014 19:52:50 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 22935 invoked by uid 89); 11 Feb 2014 19:52:49 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.4 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,RP_MATCHES_RCVD autolearn=ham version=3.3.2 X-HELO: elasmtp-scoter.atl.sa.earthlink.net Received: from elasmtp-scoter.atl.sa.earthlink.net (HELO elasmtp-scoter.atl.sa.earthlink.net) (209.86.89.67) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Tue, 11 Feb 2014 19:52:48 +0000 Received: from [68.96.200.16] (helo=macbook2.local) by elasmtp-scoter.atl.sa.earthlink.net with esmtpa (Exim 4.67) (envelope-from ) id 1WDJNu-0007Vb-GB for gdb-patches@sourceware.org; Tue, 11 Feb 2014 14:52:46 -0500 Message-ID: <52FA7F8D.8050302@earthlink.net> Date: Tue, 11 Feb 2014 19:52:00 -0000 From: Stan Shebs User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:24.0) Gecko/20100101 Thunderbird/24.3.0 MIME-Version: 1.0 To: gdb-patches@sourceware.org Subject: Re: [PATCH] Use Doxygen for internals documentation References: <52F420E0.9050203@earthlink.net> <52FA7509.4010400@earthlink.net> <201402111919.s1BJJfLP012816@glazunov.sibelius.xs4all.nl> In-Reply-To: <201402111919.s1BJJfLP012816@glazunov.sibelius.xs4all.nl> Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-ELNK-Trace: ae6f8838ff913eba0cc1426638a40ef67e972de0d01da9401f1244134b93b4973a803fe813ae6012350badd9bab72f9c350badd9bab72f9c350badd9bab72f9c X-IsSubscribed: yes X-SW-Source: 2014-02/txt/msg00364.txt.bz2 On 2/11/14 11:19 AM, Mark Kettenis wrote: >> Date: Tue, 11 Feb 2014 11:07:53 -0800 >> From: Stan Shebs >> >> On 2/6/14 3:55 PM, Stan Shebs wrote: >>> Here is the official patch for the introduction of Doxygen that I >>> proposed last fall. >> >> This is now pushed. >> >> I've added http://sourceware.org/gdb/wiki/DoxygenForGDB as the >> initial info on what to do with it. >> >> I've also got defs.h, minsyms.h, and utils.[hc] in various states >> of doxygenation, but won't spend a whole lot more time on them >> before pushing them. >> >> For other popular header files, I suggest that if people >> want to jump on any, that we use the wiki page as a simple >> reservation system - although basic doxygenation of a file >> need take only a few minutes, one invariably sees many ways >> to fix up the comment blocks. > > When did we agree that using doxygen was a good idea? We did discuss it last August as part of my original proposal, then last October with the first version of this patch. It wasn't 100% support, but there was enough to be worth the experiment. > I don't want to spend my time on uglifying the source code with stuff > that will never result in usable documentation. > > I don't want to be distracted by markup when I'm reading source code > or comments. Basically we're talking one additional asterisk per header declaration, which doesn't seem that onerous. Doxygen annotation *could* get more elaborate, but if it does, it will be because people are getting enough value out of it to want to spend time putting the additional effort in. > Most of all, I don't want to spend any time on arguing about these > stupid things. "" :-) Stan stan@codesourcery.com