Re: [PATCH] Doxygenate defs.h

[jose.marchesi@oracle.com (Jose E. Marchesi)]

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