Question

We have a function header format that we have to follow. It basically looks like this

/**
* Name: blah
*
* Parameters:
*       int foo
*       bool bar
*
* .....

We are attempting to generate some documents with doxygen, but one issue is that when we change he code to:

/**
* Name: blah
*
* Parameters:
*  \param  int foo
*  \param  bool bar
*
* .....

When Doxygen generates the html comments, it adds the Parameters title. We are required to have line 4, so this creates documents with 2 lines that say Parameters, the first is from line 4 and the second Doxygen auto inserts.

What I’m hoping I can do is either have Doxygen ignore line 4 or add have it not insert it’s own “Parameters:” title. Anyone know if this is possible?

Answer 1

The simple solution is to remove the “Parameters:” text altogether; it is entirely redundant since the Doxygen mark-up makes it perfectly clear that they are parameters!

For that matter the “Name:” label is entirely redundant too, and forces you to place the name in both the comment and the code. Why would you need that? It’s name is right there in the code. It is an unnecessary comment maintenance headache, and Doxygen will use teh name in the code not the name in the comment in the generated documentation.

If you must attempt to mix your existing format with a Doxygen compatible format it would be easier to use C++/C99 line comments rather than block comments; most C compilers support them:

// Name: blah
//
// Parameters:
/// \param  foo Description of foo
/// \param  bar Description of bar

Note \param <type> <name> is not correct Doxygen syntax; it is \param <name> <description>. Doxygen gets the type from the code; again specifying the type in the comment is entirely redundant, and another maintenance headache.

I would strongly suggest that you employ a more Doxygen and maintenance friendly function boiler-plate altogether. I use the following basic form (for what its worth):

//! @brief  Brief description
//!
//! Full description if necessary.
//! @param p1    p1 description
//! @param p2    p2 description
//! @return Return value description
int foobar( int p1, int p2 ) ;

Obviously whether you use /// or //! and \ or @ is a matter of preference.