Re: [PATCH] Doxygenate defs.h

[Mark Kettenis <mark.kettenis@xs4all.nl>]

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