From: Kristian Nielsen
Date: April 6 2010 10:58am
Subject: Re: doxygen comments in header files
List-Archive: http://lists.mysql.com/internals/37847
Message-Id: <87aatgu9so.fsf@knielsen-hq.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii

Tor Didriksen <Tor.Didriksen@stripped> writes:

> On 2010-03-31 11:53, Guilhem Bichot wrote:

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

> About your suggestion: I, and I think many others, agree with your
> suggestion.
> The main problem is implementation: how do you propose to change
> existing code (if at all?)
>
> If I write a new class with member functions, no problem, document the
> entire interface in the .h file.
> If I add a member function to a class, where should I document it? new
> or old style?
> If I change a member function of a class, should I move the documentation?

Maybe I am taking some liberties in my interpretation of the coding standard
about putting documentation at the place of implementation. But I have always
interpreted it so that I would put documentation about the *interface* of a
member function in the header. And documentation about the *implementation* of
that member function in the .cc (unless it's inline in the .h).

After all, the interface is implemented in the header, while the code is
implemented in the .cc.

So if you put the comment in the header, this is a promise to other developers
that this interface can be expected to be somewhat stable, and the method can
be used just by understanding the documentation of the interface, without
regard to how the implementation is done.

On the other hand, if you do not want / cannot give such promise, there
probably is no such well-thought out interface, and the comment is probably
better placed near the implementation, which will need to be consulted anyway
to safely use the member function.

And from this perspective I am wondering if there really is that much
disagreement between the "document in the header" vs. the "document in the
.cc" camps?

Anyway, just my .02 cents,

 - Kristian.