This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [PATCH] Doxygenate defs.h
- From: Stan Shebs <stanshebs at earthlink dot net>
- To: gdb-patches <gdb-patches at sourceware dot org>
- Date: Tue, 18 Feb 2014 16:08:31 -0800
- Subject: Re: [PATCH] Doxygenate defs.h
- Authentication-results: sourceware.org; auth=none
- References: <530285BC dot 90102 at earthlink dot net> <201402172217 dot s1HMHOAT001833 at glazunov dot sibelius dot xs4all dot nl> <5303B9E3 dot 1020406 at earthlink dot net> <CADPb22T2jrm6mWL-dh1xBevteip9MK5U1MLKZhtpT3AX_0xmPA at mail dot gmail dot com>
On 2/18/14 3:38 PM, Doug Evans wrote:
> On Tue, Feb 18, 2014 at 11:52 AM, Stan Shebs <stanshebs@earthlink.net> wrote:
>> On 2/17/14 2:17 PM, Mark Kettenis wrote:
>>>> Date: Mon, 17 Feb 2014 13:57:16 -0800
>>>> From: Stan Shebs <stanshebs@earthlink.net>
>>>>
>>>> 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