Documenting C typedefs in doxygen

Question

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?

Please specify the version of doxygen you used.

albert
– albert

2018-02-19 10:44:46 +00:00
Commented Feb 19, 2018 at 10:44 — albert
– albert, Commented Feb 19, 2018 at 10:44
Version is 1.8.13

BadZen
– BadZen

2018-02-19 20:28:55 +00:00
Commented Feb 19, 2018 at 20:28 — BadZen
– BadZen, Commented Feb 19, 2018 at 20:28

albert · Accepted Answer · 2018-02-19 10:44:21Z

8

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;

answered Feb 19, 2018 at 10:44

albert

9,2003 gold badges24 silver badges42 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

BadZen Over a year ago

Ok, so the answer seems to be "You must use the @struct tag even though the comment block comes directly before" and also "you must qualify the variable names with the name of the struct even though the comment block comes directly before" and also "you must put a newline between the @var line and the doc string". If I relax any one of these, more warnings occur. It's maybe particular of me but just don't think I can live with those (esp since syntax is javadoc-like) - too much typing / lexical real-estate. would a newer version help? Or time to find a new doc system. =/

Collectives™ on Stack Overflow

Documenting C typedefs in doxygen

1 Answer 1

1 Comment

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

1 Comment

Your Answer

Sign up or log in

Post as a guest

Related