This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [PATCH] Doxygenate defs.h
- From: Doug Evans <dje at google dot com>
- To: Stan Shebs <stanshebs at earthlink dot net>
- Cc: gdb-patches <gdb-patches at sourceware dot org>
- Date: Tue, 18 Feb 2014 15:38:15 -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>
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.