Default description of return value in Doxygen

3
votes

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?

2
c++doxygen

2 Answers

2
votes

AFAIK you can't create default description. What you can do is to use \copydoc to at least write your text 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.

1
votes

You could define an alias command with exact that return documentation:

ALIASES += "return_noerr=@return NO_ERROR on proper exit, SOME_REALLY_BAD_ERROR otherwise."

Then you can use that shortcut:

/**
 * @return_noerr
 */