From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 10149 invoked by alias); 18 Feb 2014 19:52:13 -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 10136 invoked by uid 89); 18 Feb 2014 19:52:12 -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-galgo.atl.sa.earthlink.net Received: from elasmtp-galgo.atl.sa.earthlink.net (HELO elasmtp-galgo.atl.sa.earthlink.net) (209.86.89.61) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Tue, 18 Feb 2014 19:52:12 +0000 Received: from [68.96.200.16] (helo=macbook2.local) by elasmtp-galgo.atl.sa.earthlink.net with esmtpa (Exim 4.67) (envelope-from ) id 1WFqiA-0000HG-4M for gdb-patches@sourceware.org; Tue, 18 Feb 2014 14:52:10 -0500 Message-ID: <5303B9E3.1020406@earthlink.net> Date: Tue, 18 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] Doxygenate defs.h References: <530285BC.90102@earthlink.net> <201402172217.s1HMHOAT001833@glazunov.sibelius.xs4all.nl> In-Reply-To: <201402172217.s1HMHOAT001833@glazunov.sibelius.xs4all.nl> Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-ELNK-Trace: ae6f8838ff913eba0cc1426638a40ef67e972de0d01da94083c52dc7a14cc4221b0a787037635dbf350badd9bab72f9c350badd9bab72f9c350badd9bab72f9c X-IsSubscribed: yes X-SW-Source: 2014-02/txt/msg00575.txt.bz2 On 2/17/14 2:17 PM, Mark Kettenis wrote: >> Date: Mon, 17 Feb 2014 13:57:16 -0800 >> From: Stan Shebs >> >> This is a first patch that modifies source code to be more useful with >> Doxygen. It does little more than add an extra "*" to comment blocks >> that document the source construct immediately following. >> >> In keeping with our usual practice, I have not changed anything outside >> comments, and the comments themselves are only minimally tweaked, >> despite the great temptation to expand on some of the more cryptic. :-) >> >> I'll push this in a couple days if people are willing to live with this >> format for comments. Next up, minsyms.h. > > Sorry, no, I'm not willing to live with this. It's making the > comments significantly harder to read. Really? We have a half-million lines of C, the language whose syntax is one step above line noise, and it's an extra asterisk in comment blocks that makes it significantly harder to read? :-) > And what benefit does the > documentation have over just reading the header file? Cross-links and formatting, to start with. For instance, clicking on the name of a struct in a function signature takes you to its definition. If reading the header file suffices for you, that's great, but I personally spend a lot of time grepping around and then trying to make sense of the spew. > There really is > only one thing that the old internals documentation tried to provide > that the comments in the source code aren't very good at: explaining > how the interfaces work together. And that's not something Doxygen is > going to provide. Doxygen actually has sufficient machinery to build a version of the internals manual from comment blocks in the code; I didn't lead with that because the individual construct documentation is useful to people, and a simpler starting place. But I can start with that if you like. > BTW, you realize this all violates the GNU coding standards. Really? I'd be interested in the specific passages that you think are being violated. I note that the the standards have very few hard rules that individual projects cannot decide to supersede, mostly having to do with the copyleft. I also note that libstdc++, GNU radio, and other GNU projects have been using Doxygen for some time, so it's not like GDB is even the first. Stan stan@codesourcery.com