On Thu, Nov 07, 2002 at 12:34:56PM +1100, Ben Stanley wrote:
> The first style is a summary comment, and I use these in class
> declarations, i.e. header files. The second comment type is the in depth
> documentation, which I place above the function definition. When viewing
> the HTML documentation provided by Doxygen, the class API is first
> described in summary form, using the /// comments, and later each
> function is described in depth using the /** ... */ form. There is a
> hyperlink from the short to the long.
>
> Placing the documentation closer to the code which it describes means
> that it is also more likely to be maintained as the code is modified.
> This is an important consideration.
But, it means we have to read .C files. We should put the ong form in
header files IMHO. Anybody not updating the comments when they change
the code should be strung up.
> It is possible to place the /** */ form in the header file, but then the
> headers will become quite bloated, and this will increase compilation
> time. The long form of documentation is quite easily accessible through
> the doxygen documentation, when and as required.
I challenge you to show a measurable difference in compile time (you
won't be able to). If the headers are bloated, this is a result of too
large and too complex classes ...
regards
john
--
"When a man has nothing to say, the worst thing he can do is to say it
memorably."
- Calvin Trillin
