List:Internals« Previous MessageNext Message »
From:Jay Pipes Date:June 22 2009 2:11pm
Subject:Re: MySql coding style: Request for change regarding documentation.
View as plain text  
Tor Didriksen wrote:
> 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 also find this strange.  API documentation should be with the 
declaration, not definition. This is how Drizzle does things, and also 
how a good chunk of the MySQL code base does things...

Implementation-specific documentation should go in the source files (cc 
files).  For instance, details of an algorithm or *why* a structure is 
the way it is.  But, simple descriptions of an API's methods and 
structures, IMHO, should go in the header files next to the declaration, 
not definition/implementation.

Cheers,

Jay
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