Re: A doubt about Doxygen style comments in GLOBAL

[Simon D.]

Hi.

The @NAME{} type macros can be removed address@hidden, @STRONG, @CODE, @OPTION, 
@ARG, @NAME, @XREF, @FILE, @VAR].

Sorry, I should have asked you if it was OK to use them. I added them to be 
like the style of other
 GNU documents/man pages.

The '@{' and '@}' are used to group items together with a title, they can be 
removed if necessary.
Your original code already had grouped some items together, with a comment at 
the top.

The '<br>' is used to insert a newline (you could use a macro for it, ex: '@NL' 
or '@NEWLINE'),
 they can be removed.

But the '*<' in '/**< string buffer */' needs to be present otherwise Doxygen 
won't include the comment
 'string buffer' in the documentation.

I think some of the '\' (backslashes) can be removed, but the ones with '<' and 
'>' cannot as Doxygen
 can accept HTML and XML type codes.

With the '#' in '#STRBUF', Doxygen creates a link (in the HTML output) to the 
definition of the
 structure STRBUF which the user can click on; sometimes Doxygen creates links 
automatically for
 things like 'check_malloc()' a function name (including the brackets). They 
can be removed, but
  I do not recommend it. The characters '::' can be used instead, for example 
'::STRBUF'.
 Even if you don't use the '#STRBUF' type feature, all the '#' characters in 
the text need to be
  escaped (also with '::'), for example, '#define' the C preprocessor statement 
needs to be
  '\#define' in the text.

Any character can be used within @code and @endcode, @verbatim and @endverbatim 
without
 needing to be escaped.

Do you want '@a' and '@c' removed also?  '@a' means the next word in the text 
is the name of an argument in
 the current function/method and is made italic in the Doxygen output. '@c' 
means the next word in the text is
 code and a fixed width font (like <tt> in HTML) will be used for it.   '@c' is 
used in put_brace().
 '@a' is used in normalize(), idset_add() and test() for example.

Is there anything else you would like to know or change in the Doxygen 
comments, before I change
 them?

Simon Dommett