From: Guilhem Bichot
Date: June 22 2009 3:45pm
Subject: Re: MySql coding style: Request for change regarding documentation.
List-Archive: http://lists.mysql.com/internals/36951
Message-Id: <4A3FA71A.7080505@sun.com>
MIME-Version: 1.0
Content-Type: text/plain; format=flowed; charset=UTF-8
Content-Transfer-Encoding: 8BIT

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.