Davi Arnaut a écrit, Le 07.04.2010 13:18:
> On 3/31/10 6:53 AM, Guilhem Bichot wrote:
>> 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
Experience shows that if we have
in the declaration, and
@details lots of details
in the definition, then doxygen gets it right and merges everything.