doxygen function parameter documentation (//!< vs @param)

Question

If I use "after the member" documentation for function parameters, for example, use //!< after each parameter, instead of @param in the header, the "Parameters" section is always placed after "Return" in the generated output file.

Is is possible to define the order so that "Parameters" will be placed before "Return"?

/**
 *****************************************************************************************
 *  @brief      Test API
 *
 *  @usage      This API can be called at any time
 *
 *  @return     0 if successful; or 1 if failed
 ****************************************************************************************/

int TestAPI(
    int argument1,       //!< first argument
    int argument2        //!< second argument
    );

Answer 1

I've just tried out your code with Doxygen 1.7.5.1, and confirmed that with your code, the Parameter list in the output comes after the description of Return.

This is a shame, as the //!< style is much nicer than having to re-state the names of all the parameters with @param:

/**
 *****************************************************************************************
 *  @brief      Test API
 *
 *  @usage      This API can be called at any time
 * 
 *  @param      argument1 first argument
 *  @param      argument2 second argument
 *
 *  @return     0 if successful; or 1 if failed
 ****************************************************************************************/

int TestAPI2(
    int argument1,
    int argument2
    );

I had a look in the Doxygen Bugzilla bug database, to see if it was a relatively recent bug (as then you could try reverting to an older installation).

I believe you've found Doxygen Bug 316311: 'parameter documentation after return documentation by using inline comments', which was reported in September 2005, and hasn't been fixed.

So, sadly, I'm afraid the answer to your question Is is possible to define the order so that "Parameters" will be placed before "Return"? is almost certainly No.

Edit

I've just added a note to Doxygen Bug 316311, asking for it to be changed to Status=CONFIRMED.