Doxygen -- Single Comment Block for Multiple Functions

Question

Are you able to use a single commenting block to comment multiple functions in doxygen? Below is a simple example that does not work. Can I do something similar to get what I want?

file.cpp

#include file.h

/// @name FunsGroupedInDoxygen
///@{
/**
 * @brief  Documentation for 2 functions
 * @param  aParam A Parameter
 * @retval 0 will always be returned
 */
int fun1(int aParam) {return 0;}
int fun2(int aParam) {return 0;}
///@}

file.h

int fun1(int aParam);
int fun2(int aParam);

Doxygen output:

warning: Member fun2(int aParam) (function) of file file.h is not documented.

Answer 1

Looking at grouping in the Doxygen manual here there are several methods you can use. The one that I think best fits the situation is called Member Groups.

You can define a member group using one of two styles:

///@{ 
  ...
///@}

or

/**@{*/ 
  ... 
/**@}*/

An example of this would be:

/** @name FunctionGroup
 * @brief  Documentation for 2 functions
 * @param  aParam A Parameter
 * @retval 0 will always be returned
 */
///@{
//* fun1 specific description */
int fun1(int aParam) {return 0;}
//* fun2 specific description */
int fun2(int aParam) {return 0;}
///@}

This allows you to define a group that you can provide a generic description for and still lets you drop a comment specific to each function in the created doxygen files.

I don't have doxygen installed on the computer I'm on and can't test this code directly, however if follows the example from group2 of the member groups section on the documentation, the compiled output from that example is shown here, which hopefully is the output you desire.

Edit:

After testing the previous did work for me but only when I set the desired extraction mode to All Entities (EXTRACT_ALL = YES in the doxyfile). It would be better to only use actually documented entities so I spent some time trying a different approach from the above mentioned documentation.

file.h:

/**
 * \defgroup FunctionGroup A Group of Functions
 * @brief Documentation for 2 functions
 * @param aParam A Parameter
 * @retval 0 will always be returned
 * @{
 */ 
int fun1(int aParam);
int fun2(int aParam);
 /** @} */

file.cpp:

#include file.h

/** @ingroup FunctionGroup
 * @brief fun1 specific description
 */
 int fun1(int aParam){
    return 0;
 }
/** @ingroup FunctionGroup
 * @brief fun2 specific description
 */
 int fun2(int aParam){
    return 0;
 }

Here is an image of the output I get when I run Doxygen on those two files:

I used the doxywizard on a windows machine my doxyfile generated by this is on pastebin.

Answer 2

I'm not sure about a single comment block, but a concise and easy way to do this is to use @copydoc (reference here), e.g:

/**
 * @brief Brief description
 * @param aParam A parameter
 */
void foo(int aParam) {}

/**
 * @copydoc foo(int)
 */
void bar(int aParam) {}