Use doxygen to document members of a c structure outside of the structure definition

Question

I am using doxygen to comment my C code. I am making use of a foreign API (i.e. not my own) for which documentation is scarce so I intend to document some of that API within my own source files. I do have the header file for the foreign API but it is not practical to add my own comments to that file.

Foreign Header

struct foreignstruct
{
    int a;
    int b;
};

My Header

/** My structure comments... */
struct mystruct
{
    /** Describe field here... */
    int field;
};

/** @struct foreignstruct
 *  @brief This structure blah blah blah...
 *  @??? a Member 'a' contains...
 *  @??? b Member 'b' contains...
 */

What tag do I use in place of @??? to get the correct doxygen output (where 'correct' means generated output for mystruct and foreignstruct are the same)?

Solution

Maybe one day doxygen will have a special @field tag for this, until that time, the following can be used:

/** @struct foreignstruct
 *  @brief This structure blah blah blah...
 *  @var foreignstruct::a 
 *  Member 'a' contains...
 *  @var foreignstruct::b 
 *  Member 'b' contains...
 */

Which is a short-hand notation for

/** @struct foreignstruct
 *  @brief This structure blah blah blah...
 */
/** @var foreignstruct::a 
 *  Member 'a' contains...
 */
/** @var foreignstruct::b 
 *  Member 'b' contains...
 */

Comments

[Ben]

This solution works if foreignstruct is in a file which is parsed by doxygen. Do you expect it to work if that file isn't known to doxygen? I see warning: no uniquely matching class member found for foreignstruct::a when the foreignstruct definition can't be found (which is correct because I don't want doxygen parsing that foreign header). I've tried adding the path to the header (@struct foreignstruct /full/path/to/header.h) but I get warning: the name full/path/to/header.h' supplied as the argument of the \class, \struct, \union, or \include command is not an input file`.

[doxygen]

The struct should indeed be known to doxygen. So you can either let doxygen parse the foreign header in addition to your local documentation or add a dummy definition of the struct with fields locally (but then you do not have to use @struct and @var).

[Ben]

Not what I was hoping the answer would be, but it is the answer I was expecting. Thanks for the help.