CODEWITHSUNDEEP
cdoxygen
BadZen
BadZen

Reputation: 4265

Documenting C typedefs in doxygen

Following examples in the doxygen manual, I constructed the test header test.h:

/**
 * @file test.h
 */

  /** @brief This is a struct 
   *  @var foo A foo.
   *  @var bar Also a Foo.
   *  @var baz (unused field)
   */
  typedef struct {
     int foo;
     int bar;
     char *baz;
  } whatsit;

When I use the default Doxyfile (generated with 'doxygen -g'), I see the warnings:

...test.h:11: warning: Compound whatsit is not documented

...test.h:7: warning: documented symbol `foo A Foo` was not defined

...test.h:12: warning: Member foo (variable) of class whatsit is not documented

What gives? I am under the impression from the manual that you don't need tags like @struct when the comment directly precedes the definition, and also that it is legitimate to document the member vars in the block above, and not on the same lines they are declared with /*< ... syntax. (I definitely hate the latter style...)

How can I get this to recognize the comment properly?

Upvotes: 4

Views: 10719

Answers (1)

albert
albert

Reputation: 9012

According to the documentation: 24.51 \var (variable declaration)

Indicates that a comment block contains documentation for a variable or enum value (either global or as a member of a class). This command is equivalent to \fn, \property, and \typedef.

indicating that at the \var line only the name of the variable should reside. As the variable foo does not exist but the structure member whatsit::foo you have to use the full qualified name.

Similar reasoning for the struct.

The result should be like:

/**
 * @file test.h
 */

  /** @struct whatsit
   *  This is a struct
   *
   *  @var whatsit::foo
   *    A foo.
   *  @var whatsit::bar
   *    Also a Foo.
   *  @var whatsit::baz
   *    (unused field)
   */
  typedef struct {
     int foo;
     int bar;
     char *baz;
  } whatsit;

Upvotes: 8

Related Questions