Re: Documenting non-public members

>
> I noticed this in a recent squid3/doc/Programming-Guide commit message:
>
>> \section Coding Code Conventions
> ...
>> Now that documentation is generated automatically from the
sources
>> some common comment conventions need to be adopted.
>>
>> \subsection API vs Internal Component Commenting
> ...
>> First among these is a definition seperation between
component API
>> and Internal operations. API functions and objects should
always be
>> commented and in the *.h file for the component. Internal
logics and
>> objscte should be commented in the *.cc file wherever they are
>> defined.
>
> I am not sure this is a good guideline for C++ because class data
> members should be briefly documented where they are declared (which is
> in the .h file), even if they are not a part of the API.

This is perhapse due more discussion amongst us all.
My view so far is:

 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 actually more
convenient for most functions where 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).

If we all agree that .h is the place for class internal docs, I'll accept
it. But do consider the convenience factor in mind for all future
maintainers when deciding.

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

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.

(doxygen will, as currently set, pull the parent class docs for a method
into the childs. Thus the parent has full description, child has mod
notes)

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

>
> $0.02,

and $0.01 bank fees ;-)

Amos
Received on Wed Aug 15 2007 - 16:42:55 MDT