Hello,
Davi Arnaut a écrit, Le 07.04.2010 13:18:
> On 3/31/10 6:53 AM, Guilhem Bichot wrote:
>> Hello,
>>
>> this has been debated in the past but not in the coding style committee
>> recently, so here it is.
>>
>> http://forge.mysql.com/wiki/MySQL_Internals_Coding_Guidelines says
>> "Put a comment in front of its subject. In particular, function and
>> method comments should be placed in front of implementation rather than
>> declaration. Class comments should be put in front of class declaration."
>>
>> Even though I obey the rule, and enforce it on others when I'm code
>> reviewer, I would like the rule to be changed at least for class
>> methods: I would like their comment to be in front of the declaration
>> (so inside the class declaration). In short and approximatively: in the
>> ".h" file, not in the ".cc" file.
> I would like to suggest that it is made clear that documentation in a
> header file does not exempt documentation in source files. IMHO, in the
> headers (function prototype) we should document the function "interface"
> -- that is, everything that is relevant to a user of the function (eg,
> longer description, parameters, etc), and in the source file (function
> definition), document implementation details (eg, shorter description
> and the "guts" of the function, etc).
That would be fine with me. The contract in the declaration, the guts in
the definition.
Experience shows that if we have
/**
brief description
@param blah
*/
in the declaration, and
/**
@details lots of details
*/
in the definition, then doxygen gets it right and merges everything.
