Doxygen, too heavy to maintain ?

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

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.

Answer 2

Use non-documenting comment for new features and early stages of your code. When you find your code is ready to publish, you may update docs. Also avoid repetition of argument or function names.

Answer 3

It really depends on how much information you put in your documentation.

My functions generally smaller now due to unit testing and thus the documentation is correspondingly small. Also when documenting the class itself I always have a small snippet of code to show how the class is supposed to use. I find those are the hardest to maintain but worth it so you don't get juniors bugging you asking how they use the class.

Tips:

• Only document your public interfaces.
• Only do minimal documentation about what the function does.
• Try to use an editor that has support (most do) or has a plugin.

You'll be glad when you come to edit your code in 6 months time...

Answer 4

There is seriously something wrong about the way you use comments, or how you develop.

Doxygen comments are used for external/internal documentation on interfaces. If your interfaces changes extremely fast, then you should probably sit down a thing about the architecture layout first.

If you are using doxygen to document the internal flow of functions, then you should maybe rethink this approach (and even then, this comments shouldn't change that much). When you have a function that calculates some value then a comment /// Calculating xy using the abc algrithm is definitely something that shouldn't change each day.

Answer 5

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 6

Not exactly what you're searching but this Vim plugin can generate Doxygen stub on top of your definitions. It work pretty well.

Answer 7

In my professional software experience, every time a source file is modified, a comment must be entered describing the change. These change comments are usually not in the Doxygen comment areas (unless changes are made to an interface).

I highly suggest you make commenting your code a habit. Not only is this good for when other people have to maintain or assist you with your code, but it helps when you have abandon a source file for a while (such as when management tells you to switch projects). I have found that writing comments as I code helps me understand the algorithms better.

Answer 8

Judge yourself if the below style fits your needs. It is C-affine tho, but maybe you can draw enough from it for your ends.

///\file

/// Brief description goes here
bool /// @retval 0 This is somewhat inconsistent. \n Doxygen allows several retval-descriptions but 
     /// @retval 1 will not do so for parameters. (see below)
PLL_start( 
   unsigned char busywait, ///< 0: Comment parameters w/o repeating them anywhere. If you delete this param, the
                           ///     comment will go also. \n
                           /// 1: Unluckily, to structure the input ranges, one has to use formatting commands like \\n \n
                           /// 2-32767: whatever
   int param)              ///< 0: crash \n
                           ///  1: boom \n
                           ///  2: bang!
{
   /**
    * Here goes the long explanation. If this changes frequently, you have other more grave problems than 
    * documentation. NO DOCUMENTATION OF PARAMETERS OR RETURN VALUES HERE! REDUNDANCY IS VICIOUS!
    * - Explain in list form.
    * - It really helps the maintainer to grok the code faster.
    *
    *@attention Explain misuses which aren't caught at runtime.
    *
    *@pre Context:
    * - This function expects only a small stack ...
    * - The call is either blocking or non-blocking. No access to global data. 
    *
    *@post The Foobar Interrupt is enabled. Used system resources:
    *    - FOO registers 
    *    - BAR interrupts
    */
    /**@post This is another postcondition. */
}

Answer 9

In addition to Doxygen I think you should take a look at Code Rocket.

It actually documents what's happening "inside" your methods by trawling through the actual code and comments they contain - therefore not just limiting itself to the function comment headers, which can get out of date with what the function contents actually are.

It will automatically provide you with flowchart and pseudocode visualizations of your method contents as a form of documentation.