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
