Re: [PATCH] Doxygenate defs.h

[Stan Shebs <stanshebs@earthlink.net>]

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