SzymonPajzert SzymonPajzert - 3 months ago 26
C++ Question

Default description of return value in Doxygen

I'm pimping my C++ library and using Doxygen to write a nice documentation. Let's say I declared type:

typedef enum {
NO_ERROR, ///< Everything fine.
SOME_REALLY_BAD_ERROR, ///< Something went wrong.
VERY_INFREQUENT_ERROR ///< Used only in some cases.
} ReturnType;


and use it as return values to flag possible errors in functions. Now I define a function:

/** Very important description
*
* @return NO_ERROR on proper exit, SOME_REALLY_BAD_ERROR otherwise.
*/
ReturnType ImportantFunction();


So with every function definition I have to paste the same description of the default return value (but sometimes I will return
VERY_INFREQUENT_ERROR
and write different description). So my question is:

Is there a way in Doxygen to create default description of return value, or should I just create description for infrequent cases?

Answer

AFAIK you can't create default description. What you can do is to use \copydoc to at least write your texte only once:

/**
 * \class common_ReturnType
 *
 * NO_ERROR on proper exit, SOME_REALLY_BAD_ERROR otherwise.
 */

/** Very important description
 *
 * @return \copydoc common_ReturnType
 */
ReturnType ImportantFunction();

/** Very important description with very infrequent result
 *
 * @return \copydoc common_ReturnType In very infrequent cases, VERY_INFREQUENT_ERROR.
 */
ReturnType ImportantFunctionWithInfrequentResult();

This will generate a dummy entry in your documentation for common_ReturnType. You can exclude it from the output using EXCLUDE_SYMBOLS = common_* in you configuration file.

Comments