Doxygen, how to split function documentation when parameter typedef makes signatures identical?

Question

I have to document two separate functions which, due to a typedef, seem to be interpreted as the same function, so the docs for both are combined.

Here's a very simplified example:

typedef int group;

typedef enum { INDIVIDUAL = 0, GROUP = 1, } type_to_process;    

/**************************************************************************//**
 *
 * @brief Individual function.
 *
 * @param[in] type     type to process
 * @param[in] p_int    individual number to process
 *
 *****************************************************************************/
void function(type_to_process type, int *p_int);

/****************************************************************************//**
 *
 * @brief Group function.
 *
 * @param[in] type      type to process
 * @param[in] p_group   group number to process
 *
 *****************************************************************************/
void function(type_to_process type, group *p_group);

As group is typedef'ed to an int, doxygen sees the two functions as identical.

Is there any way to have doxygen document them as separate functions?

Thanks.

They are the same function to C++. typedef(s) do not make a new type and therefore the 2 functions have identical signatures. doxygen has done you a big favour by pointing this out. — Richard Critten
You cannot overload based on typedefs alone. You'd need tag dispatching or something like that. — Baum mit Augen
Or, don't pass a pointer to int to the "individual" function? — Mats Petersson
@Richard - pedantically "the 2 functions have identical signatures" is a little misleading. There's only one function there; the header happens to have declared it twice (which is allowed). — Toby Speight
Thanks for your timely responses. I'm aware they're effectively the same function, but the code's not mine to alter, just the documentation, hence the question. Looks like I'll have to ask the coders tomorrow. — Mark S

Nicol Bolas Nicol Bolas · Accepted Answer · 2018-02-14T16:42:48

Doxygen follows the rules of C++, and the rules of C++ say that those are the same function. There's no way to make Doxygen pretend that these declarations are for different functions, just as there's no way to get C++ to pretend that these declarations are for different functions.

Doxygen, generally speaking, does not allow you to lie to the reader of the documentation.

The correct way to handle this is to actually follow C++'s overloading rules:

struct process_individual{};
struct process_group{};

void function(process_individual, int *p_int);
void function(process_group, group *p_group);

Or better yet, just give them different names, since they're not really overloads of one another. Or even better yet, don't use a pointer for the individual one:

void function(int &integer);
void function(group *p_group);

There are numerous ways to handle this, and they all boil down to not trying to use enumerators to differentiate between functions with the same signature.

Doxygen, how to split function documentation when parameter typedef makes signatures identical?

1 Answers