Re: A doubt about Doxygen style comments in GLOBAL

Hi.

The @NAME{} type macros can be removed [@EMPH, @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