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.
No need to be. In fact, it was my mistake. Though I recognized them,
I didn't regard them as a problem at the time. Now, I feel a doubt in
my spending time for reading and writing Doxygen style comments.
In a nutshell, the cost paid isn't corresponding with the profit.
> 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?
I understand that they are required for making a beautiful document.
If GLOBAL were a library, Doxygen would be the most desirable tool.
Because API document is important for a library. Users of a library
read only the document; they never read the source code.
But in fact, GLOBAL is not a library. Those who want to read GLOBAL's
source code should read the code directly without reading API document.
Then, Doxygen's tags are not useful and in fact they are annoying.
It's putting the cart before the horse. I would like to recover simple
source code.
How about restricting Doxygen style comments to only the following two
style? ('description' should be plain text)
/**< description */
/**
* @param[in] var description
* @param[out] var description
* @param[in,out] var description
* @return description
*/
Description might include strings like '#include <stdio.h>' without quote.
If they mislead Doxygen, '/**' should be changed to '/*'.
What do you think?
Regards,
Shigio
--