This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [PATCH] Doxygenate defs.h
- From: jose dot marchesi at oracle dot com (Jose E. Marchesi)
- To: Mark Kettenis <mark dot kettenis at xs4all dot nl>
- Cc: stanshebs at earthlink dot net, gdb-patches at sourceware dot org
- Date: Tue, 18 Feb 2014 12:40:50 +0100
- 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>
> 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. And what benefit does the
documentation have over just reading the header file? 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.
I am of the same opinion. Usually only managers ever "use"
Doxygen-generated "documentation" of C programs, and mostly only because
it is required as a deliverable by contractual reasons.
Most developers will just open the header files and read them, using
some indexing tool (ctags, CEDET/Emacs, whatever Eclipse uses..) for
jumping through references. IMO polluting the comments like this,
restating the obvious with marks like @param, will only make them more
difficult to read with no practical benefit: what gdb hacker will ever
fire up a Firefox or similar to find out what the parameters to some
function are?
If the decision to use Doxygen has been already taken, would it be
possible to at least avoid these @param marks?