Doxygen, too heavy to maintain? [closed]

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.

Answer 2

I feel you get back what you put into comments, 5 minutes commenting a class well will in 3 months time when the class needs to be changed by someone else other than the original author (indeed sometimes by the original author) will take much less time to get to grips with.

I second the documentation support mentioned by David, in eclipse when you refactor parameter names it will rename the parameter in your docs section for example. I am not sure I would want it doing anything else automatically to be honest.

"every time I modify the source code, I also need to change the comment" Could be you're documenting too much. You should only have to change the documentation of a function if the change to it requires you to change every caller in some way (or if not actually change, at least check to make sure they weren't relying on obsolete behaviour), of if you're introducing new functionality that a new caller will rely on. So in theory it shouldn't be a massive overhead. Small changes, like optimizations and bugfixes within the function, usually don't need documenting.