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. There is simply
no other good place to document them because there is no corresponding
definition.

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.

$0.02,

Alex.
Received on Wed Aug 15 2007 - 10:11:39 MDT