Re: [PATCH] Doxygenate defs.h

[Simon Marchi <simon.marchi@ericsson.com>]

On 14-02-18 06:40 AM, Jose E. Marchesi wrote:
> 
>     > 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?
> 

I agree that the @param adds some weight to the code, but it doesn't really bother me.

What I like of it is that it adds some form of standardization, both for the form and the content. Currently, function headers (when they exist) are usually one paragraph that sometimes describe some of the arguments. This format makes sure you have at least one statement describing the function and then one line per argument. If the structure of the comments is always the same, it might actually be easier to read, even though it's more text.

Simon

/////////////////////////////////////////////////
/// at least we're not using comments like this... oh god why.
/////////////////////////////////////////////////