学习用doxygen生成源码文档

doxygen 中的特殊标记

doxygen 包含几个特殊标记。

C/C++ 代码的预处理

为了提取信息，doxygen 必须对 C/C++ 代码进行预处理。但是，在默认情况下，它只进 行部分预处理 —— 计算条件编译语句（#if…#endif），但是不执行 宏展开。请考虑 清单 6 中的代码。

清单 6. 使用宏的C++ 代码示例

#include <cstring>
#include <rope>
#define USE_ROPE
#ifdef USE_ROPE
　#define STRING std::rope
#else
　#define STRING std::string
#endif
static STRING name;

通过源代码中定义的<USE_ROPE>，doxygen生成的文档如下：

Defines
　　#define USE_ROPE
　　#define STRING std::rope
Variables
　　static STRING name

在这里可以看 到 doxygen 执行了条件编译，但是没有对 STRING 执行宏展开。Doxyfile 中的 <ENABLE_PREPROCESSING> 标记在默认情况下设置为 Yes。为了执行宏展开，还应 该把 <MACRO_EXPANSION> 标记设置为 Yes。这会使 doxygen 产生以下输出：

Defines
　 #define USE_ROPE
　　#define STRING std::string
Variables
　　static std::rope name

如果把 <ENABLE_PREPROCESSING> 标记设置为 No，前面源代码的doxygen 输出就是：

Variables
static STRING name

注意，文档现在没有定义，而且不可能推导出 STRING 的类型。因此，总是应该把 <ENABLE_PREPROCESSING> 标记设置为 Yes。

在文档中，可能希望只展开特 定的宏。为此，除了把 <ENABLE_PREPROCESSING> 和 <MACRO_EXPANSION> 标记设置为 Yes 之外，还必须把 <EXPAND_ONLY_PREDEF> 标记设置为 Yes（这个 标记在默认情况下设置为 No），并在 <PREDEFINED> 或 <EXPAND_AS_DEFINED> 标记中提供宏的细节。请考虑 清单 7 中的代码，这里只希 望展开宏 CONTAINER。

清单 7. 包含多个宏的C++ 源代码

#ifdef USE_ROPE
　#define STRING std::rope
#else
　#define STRING std::string
#endif
#if ALLOW_RANDOM_ACCESS == 1
　#define CONTAINER std::vector
#else
　#define CONTAINER std::list
#endif
static STRING name;
static CONTAINER gList;

清 单 8 给出配置文件。

清单 8. 允许有选择地展开宏的 Doxyfile

ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
EXPAND_AS_DEFINED = CONTAINER
…

下面的doxygen 输出只展开了 CONTAINER：

Defines
#define STRING　 std::string
#define CONTAINER 　 std::list
Variables
static STRING name
static std::list gList

注意，只有 CONTAINER 宏被展开了。在 <MACRO_EXPANSION> 和 <EXPAND_ONLY_PREDEF> 都设置为 Yes 的情况下，<EXPAND_AS_DEFINED> 标记只选择展开等号操作符右边列出的宏。

对于预处理过程，要注意的最后一个 标记是<PREDEFINED>。就像用-D 开关向 C++ 编译器传递预处理器定义一样，使用 这个标记定义宏。请考虑 清单 9 中的Doxyfile。

清单 9. 定义了宏展开标记的 Doxyfile

ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
EXPAND_AS_DEFINED =
PREDEFINED = USE_ROPE= \
ALLOW_RANDOM_ACCESS=1

下面是doxygen生成的输出：

Defines
#define USE_CROPE
#define STRING　 std::rope
#define CONTAINER　 std::vector
Variables
static std::rope name
static std::vector gList

在使用<PREDEFINED> 标记时，宏应该定义

凌众科技专业提供服务器租用、服务器托管、企业邮局、虚拟主机等服务，公司网站：http://www.lingzhong.cn 为了给广大客户了解更多的技术信息，本技术文章收集来源于网络,凌众科技尊重文章作者的版权，如果有涉及你的版权有必要删除你的文章，请和我们联系。以上信息与文章正文是不可分割的一部分,如果您要转载本文章,请保留以上信息，谢谢!