This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [PATCH] Doxygenate defs.h
- From: Mark Kettenis <mark dot kettenis at xs4all dot nl>
- To: stanshebs at earthlink dot net
- Cc: gdb-patches at sourceware dot org
- Date: Mon, 17 Feb 2014 23:17:24 +0100 (CET)
- Subject: Re: [PATCH] Doxygenate defs.h
- Authentication-results: sourceware.org; auth=none
- References: <530285BC dot 90102 at earthlink dot net>
> 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. 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.
BTW, you realize this all violates the GNU coding standards.
> 2014-02-17 Stan Shebs <stan@codesourcery.com>
>
> * defs.h: Annotate comments for Doxygen.
>