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.
*
* address@hidden sb #STRBUF structure
* address@hidden s similar to @NAME{vsprintf()} <br>
* Currently the following format is supported. <br>
* address@hidden, \%d, \%\<number\>d, \%\<number\>s,
* \%-\<number\>d, \%-\<number\>s}
* address@hidden 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.
/**
* address@hidden var description
* address@hidden var description
* address@hidden, 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 <
address@hidden>
PGP fingerprint: D1CB 0B89 B346 4AB6 5663 C4B6 3CA5 BBB3 57BE DDA3