List:Internals« Previous MessageNext Message »
From:Guilhem Bichot Date:June 22 2009 3:45pm
Subject:Re: MySql coding style: Request for change regarding documentation.
View as plain text  
Hi,

Tor Didriksen a écrit, Le 22.06.2009 15:45:
> hi
> 
> 
> "function and method comments should be placed in front of
> implementation rather than declaration"
> 
> I find it quite strange that member functions should be documented in
> the .cc file rather than the .h file, especially if these are public
> member functions (part of the public interface of the class).

I agree with this proposal.
It's easier for somebody who just wants to know how to use a module (as 
opposed to understanding how it works inside), to read the .h (API) 
instead of the .cc.
And it makes things more uniform. Consider that with the current style 
we have to do this in the .h file:

/** description of class A */
class A
{
   /** description of x */
   int x;
   /** description of f */
   int f() { return x+14;}
   /** description of h */
   virtual int h()= 0;
   int g();
}

and in the .cc file:

/** description of g */
int A::g()
{
  ...
}

That is: members variables, inline member functions and pure virtual 
member functions all have to be documented in the .h (because that's the 
only place where they are declared and defined), but the normal member 
function has to be documented in the .cc. It is an annoying exception.
Thread
MySql coding style: Request for change regarding documentation.Tor Didriksen22 Jun
  • Re: MySql coding style: Request for change regarding documentation.Jay Pipes22 Jun
    • Re: MySql coding style: Request for change regarding documentation.Michael Widenius24 Jun
      • Re: MySql coding style: Request for change regarding documentation.MARK CALLAGHAN24 Jun
        • Re: MySql coding style: Request for change regarding documentation.Manyi Lu - Sun Norway25 Jun
      • Re: MySql coding style: Request for change regarding documentation.Tor Didriksen25 Jun
      • Re: MySql coding style: Request for change regarding documentation.Joerg Bruehe25 Jun
  • Re: MySql coding style: Request for change regarding documentation.Konstantin Osipov22 Jun
    • Re: MySql coding style: Request for change regarding documentation.MARK CALLAGHAN23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Konstantin Osipov23 Jun
    • Re: MySql coding style: Request for change regarding documentation.Manyi Lu - Sun Norway23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Konstantin Osipov23 Jun
  • Re: MySql coding style: Request for change regarding documentation.Guilhem Bichot22 Jun
  • Re: MySql coding style: Request for change regarding documentation.Dmitry Lenev22 Jun
    • Re: MySql coding style: Request for change regarding documentation.Tor Didriksen23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Dmitry Lenev23 Jun
        • Re: MySql coding style: Request for change regarding documentation.Tor Didriksen23 Jun
      • Re: MySql coding style: Request for change regarding documentation.Michael Widenius24 Jun