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

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

Headers: Easier to read the comments since there is less other "noise" 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 multiple places without having to write it several times ( better for maintenance )

You could however also get the results copied over to different file documentation with a simple command. E.g. :-

My file1.h

/**
 * \brief Short about function
 *
 * More about function
 */
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 you less noise in the code files at the same time you get the documentation written in one place presented in several places in the final output.

Answer 3

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 4

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 5

I'm using QtCreator for programming. A very useful trick consists in Ctrl-Clicking on a function or method to get the declaration in the header file.

When the method is commented in the header file, you can quickly find the information you are looking for. So for me, comments should be located in the header file!

Answer 6

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;
}