18

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)?

Andrew Cottrell
  • 3,312
  • 3
  • 26
  • 41
Ben
  • 1,339
  • 1
  • 11
  • 15

1 Answers1

26

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...
 */
doxygen
  • 14,341
  • 2
  • 43
  • 37
  • 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`. – Ben Aug 30 '11 at 00:06
  • 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). – doxygen Aug 31 '11 at 17:01
  • Not what I was hoping the answer would be, but it is the answer I was expecting. Thanks for the help. – Ben Sep 01 '11 at 02:10