Using Doxygen 1.8.7, soon to be upgraded to 1.8.17.
I'm editing documentation in a C library which declares the same symbol in three different headers. The three declarations have doc comments that put the symbol in three different groups with different descriptions. C is fine with this, as long as no two of the three headers are used together. Doxygen considers it a multiple declaration, issues three warnings, and ignores two of the definitions.
What's the best way to deal with this?
The only solution I've found is the #ifndef/#endif trick described in https://www.doxygen.nl/manual/faq.html#faq_code. This would let me stuff all three symbol descriptions into one symbol declaration's Doxygen comment and tell Doxygen to ignore the other two. But the description will appear in only one group, which will be the right group for only one of the three declarations.
To illustrate the problem, header file aaa.h has a declaration like this:
/**
* This little piggy goes to market.
*/
#define PIGGY 3.1415926
Header file bbb.h has this:
/**
* This little piggy stays home.
*/
#define PIGGY 0.0
And header file ccc.h has this:
/**
* This little piggy eats roast beef, or is a vegetarian and doesn't eat
* beef at all.
*/
#define PIGGY -1.0
Is there a better way?
Telling the engineer to clean up the code is not a solution. I'm in a working culture where engineers are very unlikely to change code on an editor's request. We're too late in the release cycle for them to do that even if they agree.