[Top][All Lists]

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

A doubt about Doxygen style comments in GLOBAL

From: Shigio YAMAGUCHI
Subject: A doubt about Doxygen style comments in GLOBAL
Date: Thu, 11 Jun 2015 07:23:17 +0900

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 */
/** @} */


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


Shigio YAMAGUCHI <address@hidden>
PGP fingerprint: D1CB 0B89 B346 4AB6 5663  C4B6 3CA5 BBB3 57BE DDA3

reply via email to

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