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

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

Headers: Easyer to read the comments since thre is less other "niose" when looking at the files.

Source: Then you have the actual functions available for reading while looking at the comments.

We just use all global functions commented in headers and local functions commented in source. If you want you can also include the copydoc command to insert the documentation in mulitiple places without having to write it several times ( better for maintenance )

You could however also get the results copyed over to diffrent file documentation with a simple command.

Eks:

My file1.h

/**
 * \brif Short about function
 *
 * More about fucntion
 */
WORD my_fync1(BYTE*);

MY file1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

Now you get the same documentation on both functions.

This gives tou less noise in the code files at the same time you get the docmumentation written in one place presented in several plaves in the final output

Answer 2

Usually I put documentation for interface (\param, \return) in .h file and documentation for implementation (\details) in .c/.cpp/.m file. Doxygen groups everything in the function/method documentation.

Answer 3

I put everything in the header file.

I document everything, but only generally extract the public interface.

Answer 4

Having comments in the header means that all users of a class must be recompiled if a comment is changed. For a large projects, coders will be less inclined to update comments in headers if they risk spending the next 20min rebuilding everything.

And.. since you're supposed to read the html doc and not browse through the code for documentation, it's not a large problem that the comment blocks are more difficult to locate in the source files.

Answer 5

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!