Re: Documenting non-public members

(pulling this back into squid-dev. private response was a slip of the
paste key.)

> 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

Ah, I mean "user" as someone writing code (A) somewhere than needs to use
an object (B)s' interface to make it do stuff. Rather than writing new
code inside object B itself.

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

... Um... Thats the way I had it. <looking ahead to see ones' own back ... />

Amos
Received on Wed Aug 15 2007 - 22:18:27 MDT