List:Internals« Previous MessageNext Message »
From:Guilhem Bichot Date:April 7 2010 11:59am
Subject:Re: doxygen comments in header files
View as plain text  
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.

Thread
doxygen comments in header filesGuilhem Bichot31 Mar
  • Re: doxygen comments in header filesTor Didriksen6 Apr
    • Re: doxygen comments in header filesGuilhem Bichot6 Apr
      • Re: doxygen comments in header filesMats Kindahl6 Apr
    • Re: doxygen comments in header filesKristian Nielsen6 Apr
      • Re: doxygen comments in header filesGuilhem Bichot9 Apr
        • Re: doxygen comments in header filesTimour Katchaounov11 Apr
          • Re: doxygen comments in header filesDavi Arnaut11 Apr
            • Re: doxygen comments in header filesDavi Arnaut11 Apr
            • Re: doxygen comments in header filesSergei Golubchik11 Apr
              • Re: doxygen comments in header filesGuilhem Bichot12 Apr
                • Re: doxygen comments in header filesTor Didriksen12 Apr
                  • Re: doxygen comments in header filesGuilhem Bichot12 Apr
                    • Re: doxygen comments in header filesTor Didriksen12 Apr
                  • Re: doxygen comments in header filesSergei Golubchik12 Apr
            • Re: doxygen comments in header filesMichael Widenius13 Apr
              • Re: doxygen comments in header filesDavi Arnaut13 Apr
    • Re: doxygen comments in header filesMichael Widenius6 Apr
      • Re: doxygen comments in header filesMARK CALLAGHAN6 Apr
        • Re: doxygen comments in header filesMichael Widenius13 Apr
  • Re: doxygen comments in header filesDavi Arnaut7 Apr
    • Re: doxygen comments in header filesGuilhem Bichot7 Apr
    • Re: doxygen comments in header filesKonstantin Osipov9 Apr
  • Re: doxygen comments in header filesIngo Strüwing12 Apr
    • Re: doxygen comments in header filesGuilhem Bichot15 Apr
      • Re: doxygen comments in header filesIngo Strüwing15 Apr
        • RE: doxygen comments in header filesVladislav Vaintroub16 Apr