List:Internals« Previous MessageNext Message »
From:Davi Arnaut Date:April 7 2010 11:18am
Subject:Re: doxygen comments in header files
View as plain text  
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.
>
> Like this:
> class C
> {
> /** comment (@param etc @retval etc) */
> method();
> }
>
> My reasons:
> 1) imagine a class with members, pure virtual methods, inline methods,
> and non-inline methods. The three first have their definition in the
> class's declaration, and only the fourth has its definition in the .cc
> file. Then the current rule suggests this:
>
> class C
> {
> member; /** comment */
> pure virtual method; /** comment */
> method; /** no comment, as definition is in .cc */
> inline_method { code }; /** comment */
> }
> and I find this inconsistent: only for "method" do you have to look up
> the comment in the .cc file.
>
> 2) if I want to help the API user, who in theory can ignore the
> implementation (the .cc) and concentrate on the API (the .h), it's
> better if descriptive comments are in the .h. The comment in the .h can
> tell what to give to the method and what to expect from it, that's all
> the API user needs to know.
>
> 3) it's also easier for design reviews: if descriptive comments are in
> the .h I can just paste the .h to the design reviewer, it makes a
> self-documenting design.
>
> I know the current rule is liked by some and has upset others, so I
> suggest this be discussed by the Coding style committee (note: I'm not
> in it anymore).
> Thanks!
>

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).

Regards,

Davi
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