(Sorry for the repeat, should have sent to the list)
I spoke to Sage for a bit about documentation. Here is what we ended up
with:
/**
* Brief class comment ending with this period. Not part of the brief
comment.
*
* Details here.
* Etc.
*/
class Foo {
/// Comment for the member following.
int member;
/** Brief function comment up to this period.
*
* More details.
* @param count [in] How many.
* @param retval [out] Returned string.
* @return Error Code
*/
int gen_foo_string(int count, string *reval);
/** Brief function comment again.
* @return Error Code
*/
int gen_foo_string2(int count, ///< [in] How many.
string *retval); ///< [out] Returned
String.
};
Doxygen allows a variety of commenting styles, so it probably makes
sense to standardise on one. The above is based on the Javadoc style.
/** or /// indicate the beginning of a Doxygen comment. Parameters can
either be documented before the function declaration (as in
gen_foo_string) or inline with the parameters as in gen_foo_string2.
The latter approach seems to have two benefits. First, that it's
difficult to change the parameters without changing the documentation.
Second, that you don't need to duplicate the parameter name or add
@param. However, longer comments become unwieldy. I suggest we use the
gen_foo_string2 style when it's convenient and the gen_foo_string style
when we need longer comments.
Questions? Comments? Criticisms?
-Sam
--
To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
