Re: [PATCH] Doxygenate defs.h

[Doug Evans <dje at google dot com>]

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).

>> And what benefit does the
>> documentation have over just reading the header file?

One thing I like about Doxygen is the improved S/N ratio when trying
to understand what the API of any particular module provides.  Headers
help a bit, but not completely, but it's now worse because when I want
to edit a function I now have two files to potentially deal with.
Plus I *have* to write a silly little one liner at the function
definition site that says "go see the .h".   Blech!  If I were allowed
to disapprove of the move of function documentation to headers I
would.

> 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.

I like the benefit of an internals manual coming from the code.