doxygen 将宏类型错误渲染为公共成员函数

Question

我正在使用类型宏 list(type)，它扩展为动态类型 [list_of_type]，如下所示：

主sn-p

...
#define list(type) force_append_macro(list_of_,type)
...
typedef struct _improperlydocumented
{
  list(char_ptr) *words;
}improperlydocumented;
...

问题

doxygen 错误地将这种类型 [list(char_ptr)] 渲染为 公共成员函数（而不是成员数据）。

环境信息

$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description:    Ubuntu 14.04.1 LTS
Release:    14.04
Codename:   trusty

$ doxygen --version
1.8.6

doxygen 向导生成以下输出：

doxygen -g

我的代码/配置：

---

doxygen.config

PROJECT_NAME           = "doxytest"
OUTPUT_DIRECTORY       = ./build/docs
OPTIMIZE_OUTPUT_FOR_C  = YES

TYPEDEF_HIDES_STRUCT   = YES

HIDE_SCOPE_NAMES       = YES
SHOW_NAMESPACES        = NO
INPUT                  = ./
FILE_PATTERNS          = *.h *.c

GENERATE_HTML          = YES
GENERATE_LATEX         = NO

ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = NO
EXPAND_ONLY_PREDEF     = YES
SEARCH_INCLUDES        = YES
INCLUDE_PATH           = 
INCLUDE_FILE_PATTERNS  = 
PREDEFINED             =
EXPAND_AS_DEFINED      = 

注意：我尝试设置EXPAND_AS_DEFINED = list；与下面的输出相同..

list.h

#ifndef __list__
#define __list__

typedef struct 
{
  int capacity,
      count,
      objsize,
      xprate;
  void *data;
}glist_t;

/* allow list types to be defined (as wrappers around generic_list) */
#define append_macro(a,b) a ## b
#define force_append_macro(a,b) append_macro(a,b)
#define declare_named_list_type(name,type) typedef union\
                                           {struct force_append_macro(_template_,name)\
                                             {\
                                               int capacity,\
                                               count,\
                                               objsize,\
                                               xprate;\
                                               type *data;\
                                             }template;\
                                             glist_t ls;\
                                           }name
#define declare_list_type(type) declare_named_list_type(force_append_macro(list_of_,type),type)
#define list(type) force_append_macro(list_of_,type)

typedef char * char_ptr;
declare_list_type(char_ptr);

/*!
 * This object is improperly documented.
 *
 * Issue is that the list(char_ptr) is treated as a member function instead of a type..
 */

typedef struct _improperlydocumented
{
  list(char_ptr) *words;
}improperlydocumented;

#endif

氧气输出

未正确记录的结构参考

---

#include

公共成员函数

---

list (char_ptr)*words

详细说明

---

此对象的文档记录不正确。

问题是 list(char_ptr) 被视为成员函数 而不是类型..

---

问题

如何将 doxygen 输出修复为文档 words 作为成员数据（不是公共成员函数）？

---

配置尝试

PROJECT_NAME           = "doxytest"
OUTPUT_DIRECTORY       = ./build/docs
OPTIMIZE_OUTPUT_FOR_C  = YES

TYPEDEF_HIDES_STRUCT   = YES

HIDE_SCOPE_NAMES       = YES
SHOW_NAMESPACES        = NO
INPUT                  = ./
FILE_PATTERNS          = *.h *.c

GENERATE_HTML          = YES
GENERATE_LATEX         = NO

ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES|NO **
SEARCH_INCLUDES        = YES
INCLUDE_PATH           = 
INCLUDE_FILE_PATTERNS  = 
PREDEFINED             =
EXPAND_AS_DEFINED      = list

** 在所有其他设置相同的情况下尝试了 YES 和 NO（不包括星号；）

PROJECT_NAME           = "doxytest"
OUTPUT_DIRECTORY       = ./
OPTIMIZE_OUTPUT_FOR_C  = YES

TYPEDEF_HIDES_STRUCT   = YES

HIDE_SCOPE_NAMES       = YES
SHOW_NAMESPACES        = NO
INPUT                  = ./
FILE_PATTERNS          = *.h *.c

GENERATE_HTML          = YES
GENERATE_LATEX         = NO

ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = NO
SEARCH_INCLUDES        = YES
INCLUDE_PATH           = 
INCLUDE_FILE_PATTERNS  = 
PREDEFINED             =

仍然没有正确扩展列表（char_ptr）。输出没有变化

我试图通过复制+粘贴上面的配置和 list.h 文件来复制 Windows 上的工作场景（下面讨论）：

Answer 1

来自 Doxygen 文档

EXPAND_ONLY_PREDEF

如果 EXPAND_ONLY_PREDEF 和 MACRO_EXPANSION 标记都设置为 YES，则宏扩展仅限于使用指定的宏 PREDEFINED 和 EXPAND_AS_DEFINED 标签。

默认值为：否。

此标签要求标签 ENABLE_PREPROCESSING 设置为 YES。

EXPAND_AS_DEFINED

如果 MACRO_EXPANSION 和 EXPAND_ONLY_PREDEF 标签设置为 YES，那么该标签可用于指定宏名称列表 被扩大。在源代码中找到的宏定义将是 用过的。如果要使用不同的宏，请使用 PREDEFINED 标记 覆盖源代码中的定义的定义。

此标签要求标签 ENABLE_PREPROCESSING 设置为 YES。

因此，EXPAND_AS_DEFINED 选项只有在 MACRO_EXPANSION 选项被指定为 yes（它不是）时才有效。

所以只需将MACRO_EXPANSION 指定为yes 并将list 添加到EXPAND_AS_DEFINED。这将解决您的问题。

编辑

以下配置（仅相关选项）已在 Doxygen 1.8.5、1.8.6 和 1.8.9.1（Win7 下）测试：

PROJECT_NAME           = "doxytest"
OUTPUT_DIRECTORY       = ./
OPTIMIZE_OUTPUT_FOR_C  = YES

TYPEDEF_HIDES_STRUCT   = YES

HIDE_SCOPE_NAMES       = YES
SHOW_NAMESPACES        = NO
INPUT                  = ./
FILE_PATTERNS          = *.h *.c

GENERATE_HTML          = YES
GENERATE_LATEX         = NO

ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = NO
SEARCH_INCLUDES        = YES
INCLUDE_PATH           = 
INCLUDE_FILE_PATTERNS  = 
PREDEFINED             =

其他选项保留其默认值。

生成的输出是：

未正确记录的结构参考

---

#include <list.h>

公共成员函数

---

list_of_char_ptr* words

详细说明

---

此对象的文档记录不正确。

问题是 list(char_ptr) 被视为成员函数 而不是类型..