Where to put the doxygen comment blocks for an internal library - in H or in CPP files? [closed]

Question

The common sense tells that the Doxygen comment blocks have to be put in the header files where the classes, structs, enums, functions, declarations are. I agree that this is a sound argument for a libraries that are mean to be distributed without its source (only headers and libs with object code).

BUT...I've been thinking of the exact opposite approach when I'm developing an internal to the company (or as a side project for myself) library that will be used with its full source code. What I propose is to put the large comment blocks in the implementations files (HPP, INL, CPP, etc) in order NOT to clutter the inteface of the classes and functions declared in the header.

Pros:

• Less clutter in the header files, only categorizing of the functions can be added.
• The comment blocks that are previewed when Intellisense for example is used doesn't clash - this is a defect that I have observed when I have a comment block for a function in the .H file and have its inline definition in the same .H file but included from .INL file.

Cons:

• (The obvious one) The comment blocks are not in the header files where the declarations are.

So, what do you think and possibly suggest?

Answer 1

Put the documentation where people will read and write it as they are using and working on the code.

Class comments go in front of classes, method comments in front of methods.

That is the best way to make sure things are maintained. It also keeps your header files relatively lean and avoids the touching issue of people updating method docs causing headers to be dirty and triggering rebuilds. I have actually known people use that as an excuse for writing documentation later!

Answer 2

I like to make use of the fact that names can be documented in multiple places.

In the header file, I write a brief description of the method, and document all its parameters - these are less likely to change than the implementation of the method itself, and if they do, then the function prototype needs to be changed in any case.

I put long-format documentation in the source files next to the actual implementation, so the details can be changed as the method evolves.

For example:

mymodule.h

/// @brief This method adds two integers. /// @param a First integer to add. /// @param b Second integer to add. /// @return The sum of both parameters. int add(int a, int b); 

mymodule.cpp

/// This method uses a little-known variant of integer addition known as /// Sophocles' Scissors. It optimises the function's performance on many /// platforms that we may or may not choose to target in the future. /// @TODO make sure I implemented the algorithm correctly with some unit tests. int add(int a, int b) {   return b + a; }