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.
