Re: Documenting non-public members

On Thu, 2007-08-16 at 10:40 +1200, Amos Jeffries wrote:

> Most of the squid code is commented for programmers in the .cc where the
> code is written. Leaving that as-is where possible, this is actual more
> convenient for most functions as editors can change code and description
> in one place.
>
> BUT, API stuff MUST be written in the .h since there is no guarantee of
> the user(s) having time to find and read the .cc (or it even being
> available).

I am not sure how you distinguish code users from developers, but I
agree that APIs (whatever that is) should be documented in (or its
documentation should be referenced from) .h files.

> > There is simply
> > no other good place to document them because there is no corresponding
> > definition.
>
> There is the place where the {...} code itself lives. Which is the written
> intention there. I picked this because that is the current documenting
> style for squid.

Class data members do not have a single place where they live inside the
code. IMO, virtually every data member should be briefly documented in
the .h file. If one cannot express what the data member "means" in one
short line, it is a good indication of a poor design.

Similar things can be said about groups of data and function members:
There is no place to document groupings in .cc file because member
definitions are far from each other.

> The edge case here is virtual functions defined as virtual foo Bar(){} in
> the .h file itself.
> Those needs a brief comment saying class X defined as empty or do-nothing.

Actually, placing a .h comment that bar() implementation does nothing is
a dangerous practice! The child should not care or rely upon specific
parent's implementation of a virtual method because that implementation
may change. What does matter for the child is whether the parent method
should be called by the child. And, sometimes, whether it should be
called before or after the child code.

> > A short description of methods should also be appropriate (and is often
> > very helpful) in .h file, even if they are not a part of public API.
>
> True, we can do this regardless of where the detail description is. ANY
> auto-docs comment in .h or .cc(i) just ahead of a object-name are
> catenated for the final product.

It is much easier for me to find short member descriptions/briefs in
a .h file than in a .cc file, but if somebody is browsing doxygen pages,
there should indeed be no difference.

My rule of thumb is to place API descriptions and "what is it?" briefs
in .h files and "how/why/etc" implementation notes in .cc files.

Cheers,

Alex.
Received on Wed Aug 15 2007 - 22:32:13 MDT