From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 6138 invoked by alias); 19 Feb 2014 00:08:36 -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 6124 invoked by uid 89); 19 Feb 2014 00:08:35 -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; Wed, 19 Feb 2014 00:08:35 +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 1WFuiF-0004Ov-OH for gdb-patches@sourceware.org; Tue, 18 Feb 2014 19:08:31 -0500 Message-ID: <5303F5FF.3060509@earthlink.net> Date: Wed, 19 Feb 2014 00:08: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 Subject: Re: [PATCH] Doxygenate defs.h References: <530285BC.90102@earthlink.net> <201402172217.s1HMHOAT001833@glazunov.sibelius.xs4all.nl> <5303B9E3.1020406@earthlink.net> In-Reply-To: Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-ELNK-Trace: ae6f8838ff913eba0cc1426638a40ef67e972de0d01da94039a4818faf22245e0de86275829a23b0350badd9bab72f9c350badd9bab72f9c350badd9bab72f9c X-IsSubscribed: yes X-SW-Source: 2014-02/txt/msg00583.txt.bz2 On 2/18/14 3:38 PM, Doug Evans wrote: > On Tue, Feb 18, 2014 at 11:52 AM, Stan Shebs wrote: >> 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? :-) > > I don't find the new defs.h significantly harder to read at all. > I wonder though, having seen it in action so to speak, if "/* * " > could be replaced with "/** " (same as now with the space between the > * * deleted). If the "/** " is on the same line as text, Emacs will want to indent the rest of the block by 4, instead of the usual 3. The other option is to put the "/**" on a line by itself, which is plausible but wastes a line of screen space. "/* * " is the least-disruptive option I could find. The filter turns "/* * " into "/** " so that Doxygen recognizes it as special for its processing. We could use just about any other string that is distinctive, but alternatives like "/* ! " don't seem like much of an improvement. Stan stan@codesourcery.com