Where to place doxygen comment blocks for internal library - in H or in CPP files?

Question

Common sense dictates that Doxygen comment blocks should be placed in header files where classes, structures, enumerations, functions, declarations are represented. I agree that this is a sound argument for libraries that should be distributed without its source (only headers and libraries with object code).

BUT ... I was thinking about the exact opposite approach when I am developing an internal library (or as a side project for myself) that will be used with the full source code. I suggest placing large comment blocks in the implementation files (HPP, INL, CPP, etc.), so as not to clutter up the interface of the classes and functions declared in the header.

Pros:

• Less clutter in header files; only function categorization can be added.
• Comment blocks that are viewed when using Intellisense, for example, do not conflict - this is a defect that I observed when I have a comment block for a function in a .H file and has a built-in definition in the same .H, but is included in the .INL file.

Minuses:

• (Obvious) Comment blocks are not in the header files where the ads are indicated.

So what do you think and perhaps suggest?

Answer 1

Put the documentation where people will read and write it when they use and work on the code.

Class comments go before classes, method comments before methods.

This is the best way to make sure everything is supported. It also keeps your header files relatively sparse and avoids problematic people updating docs that cause headers to become dirty and trigger rebuilds. I really knew that people use this as an excuse for writing documentation later!

Answer 2

I like to use the fact that names can be documented in several places.

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

I put the long format documentation in the source files next to the actual implementation, so the details may change 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 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; } 

Answer 3

The presence of comments in the title means that all users of the class must be recompiled if the comment is changed. For large projects, coders will be less likely to update comments in headings if they risk spending the next 20 minutes restoring everyone.

And .. since you have to read the html document and not look at the documentation code, this is not a big problem because comment blocks are harder to find in the source files.

Answer 4

Headings: It’s easier to read comments because there are fewer other “noises” when viewing files.

Source: Then you have the actual functions available for reading when viewing comments.

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

You can also get results copied to other file documentation with a simple command. For example.: -

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 for both functions.

This gives you less noise in the code files at the same time as getting documentation written in one place, presented in several places in the final release.

Answer 5

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

Answer 6

I put everything in the header file.

I document everything, but only usually extract the open interface.

Answer 7

I am using QtCreator for programming. A very useful trick is to Ctrl-Click on a function or method to get the declaration in the header file.

When a method is commented in the header file, you can quickly find the information you need. Therefore, for me, comments should be located in the header file!

Answer 8

In C ++, sometimes an implementation can be split between the header and .cpp modules. It seems cleaner here to place the documentation in the header file, as this is the only place where all public functions and methods are guaranteed.