c - 在 doxygen 中记录 C 类型定义

Question

按照doxygen手册中的例子，我构建了测试头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;

当我使用默认 Doxyfile 时(使用“doxygen -g”生成)，我看到警告:

...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

什么给了？手册给我的印象是您不需要 @struct 这样的标签当注释直接在定义之前时，并且在上面的 block 中记录成员变量是合法的，而不是在用 /*< ... 声明的同一行上句法。 (我绝对讨厌后一种风格……)

我怎样才能让它正确识别评论？

Answer 1

根据文档: 24.51\var(变量声明)

表示注释 block 包含变量或枚举值(全局或类成员)的文档。此命令等效于\fn、\property 和\typedef。

表示在\var 行中只应包含变量名。由于变量 foo 不存在但结构成员 whatsit::foo 您必须使用完整的限定名称。

结构的类似推理。

结果应该是这样的:

/**
 * @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;