Re: [PATCH] Doxygenate defs.h

[Yao Qi <yao@codesourcery.com>]

On 02/18/2014 07:40 PM, Jose E. Marchesi wrote:
> 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?

I feel @param is useful here.  "@param arg" is equivalent to "ARG" we
are using in comments nowadays, but more descriptive, IMO.  It should
not confuse any GDB newbie.  Some refactor tools can update @param when
argument is renamed, to keep comments consistent with code.

We use doxygen to generate internal documentation from source code, not
only function comments, but also general overview of each 'module'.  It
isn't hard to understand each function comments but hard to get a big
picture of each 'module'.  Doxygen helps!

-- 
Yao (齐尧)