A doubt about Doxygen style comments in GLOBAL

Hi all,
Recently, I have a doubt about use of Doxygen style comments
in GLOBAL's source code.

I think there is a problem in the following comments.

/** @{ */
STRBUF *sb;                     /**< string buffer */
/** @} */

or

/**
 * strbuf_vsprintf: do @NAME{vsprintf} into string buffer.
 *
 *      @param[in]      sb      #STRBUF structure
 *      @param[in]      s       similar to @NAME{vsprintf()} <br>
 *                      Currently the following format is supported. <br>
 *                      @CODE{\%s, \%d, \%\<number\>d, \%\<number\>s,
 *                      \%-\<number\>d, \%-\<number\>s}
 *      @param[in]      ap       <br>
 */

The meta tokens in the comment like '@{', '@}', '<', '@NAME', '#',
'@CODE', '\', '<br>' are gloomy. These are very difficult to read, and
are not beautiful for me. Though I understand it is required for making
beautiful document, I don't want to make a mess on the source code in
exchange for document. First of all, from the start to use this style,
writing code became no longer fun for me.

So, I would like to stop Doxygen style comment except for function headers
as follows.

/**
 *      @param[in] var description
 *      @param[out] var description
 *      @param[in, out] var description
 * @return description
 */

I can accept the comment above as one of desirable styles.
('description' should be plain text, though)

Any comment?

Regards,
Shigio


-- 
Shigio YAMAGUCHI <[email protected]>
PGP fingerprint: D1CB 0B89 B346 4AB6 5663  C4B6 3CA5 BBB3 57BE DDA3

_______________________________________________
Bug-global mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/bug-global