Question

I am currently starting using doxygen to document my source code. I have notice that the syntax is very heavy, every time I modify the source code, I also need to change the comment and I really have the impression to pass too much time modifying the comment for every change I make in the source code.

Do you have some tips to document my source code efficiently ?

Does some editor (or plugin for existing editor) for doxygen to do the following exist?

• automatically track unsynchronized code/comment and warn the programmer about it.
• automatically add doxygen comment format (template with parameter name in it for example) in the source code (template) for every new item

PS: I am working on a C/C++ project.

Answer 1

Is it the Doxygen syntax you find difficult? Or is it the fact that you have to comment all of the functions now.

If it’s the former, there may be a different tool that fits your coding style better. Keep in mind that Doxygen supports multiple commenting styles, so experiment until you find one you like.

If it’s the latter, then tough it out. As a good programming practice, every public-facing function should have a comment header that explains:

1. What the function does
2. The parameters
3. The return codes
4. Any major warnings/limitations about the function.

This is true regardless of the documentation tool you use.

My big tip: Avoid the temptation to comment too much. Describe what you need, and no more. Doxygen gives you lots of tags, but you don’t have to use them all.

• You don’t always need a @brief and a detailed description.
• You don’t need to put the function name in the comments.
• You don’t need to comment the function prototype AND implementation.
• You don’t need the file name at the top of every file.
• You don’t need a version history in the comments. (You’re using a version control tool, right?)
• You don’t need a “last modified date” or similar.

As for your question: Doxygen has some configuration options to trigger warnings when the comments don’t match the code. You can integrate this into your build process, and scan the Doxygen output for any warnings. This is the best way I have found to catch deviations in the code vs comments.