[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: A doubt about Doxygen style comments in GLOBAL

From: Simon D.
Subject: Re: A doubt about Doxygen style comments in GLOBAL
Date: Sat, 13 Jun 2015 03:49:52 +0100


The @NAME{} type macros can be removed address@hidden, @STRONG, @CODE, @OPTION, 

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

Simon Dommett

reply via email to

[Prev in Thread] Current Thread [Next in Thread]