在构建文档时，如何让 doxygen 忽略类似函数的宏？答案

【问题标题】：how do i make doxygen ignore function-like macros when building the documentation?在构建文档时，如何让 doxygen 忽略类似函数的宏？
【发布时间】：2014-02-11 09:41:35
【问题描述】：

我需要用 doxygen 记录一个项目，但还需要忽略一些宏，我在我的代码的小部分中使用这些宏来提高可读性，因为这些宏出现在文档中是没有意义的。

这是一个最小的例子（我主要使用宏来索引一些 C 风格的 2D 或 3D 数组）：

#include <cstring>
/*! \file notes.cpp
  \brief A test for macros and doxygen
*/
/// my main function
int main ()
{
   double loc_arr[9][4][4];
   memset (loc_arr, 0.0, 144 * sizeof (double));
#define BLOCK(i) (&(loc_arr[i][0][0]))
   for (int ii = 0; ii < 9; ++ii)
   {
     memset (BLOCK(ii), double(ii), 16 * sizeof (double));
   }
#undef BLOCK
   return 1;
}

当我 doxy 时，使用以下设置：

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

我得到这个：

请注意，我可以避免记录宏的唯一方法是设置 ENABLE_PREPROCESSING = NO ，这对我来说是个问题，因为它还消除了页面顶部的包含图。

【问题讨论】：

标签： doxygen preprocessor-directive

【解决方案1】：

选项1。您可以使用预处理器符号DOXYGEN_SHOULD_SKIP_THIS，如doxygen FAQ中所述

How can I make doxygen ignore some code fragment?

The new and easiest way is to add one comment block with a
\cond command at the start and one comment block with a
\endcond command at the end of the piece of code that should be
ignored. This should be within the same file of course.

But you can also use doxygen's preprocessor for this: If you put

#ifndef DOXYGEN_SHOULD_SKIP_THIS

 /* code that must be skipped by Doxygen */

#endif /* DOXYGEN_SHOULD_SKIP_THIS */

around the blocks that should be hidden and put:

  PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS

in the config file then all blocks should be skipped by doxygen
as long as ENABLE_PREPROCESSING is set to YES.

选项 2。 您可以使用 EXCLUDE_SYMBOLS doxygen 的配置选项。

【讨论】：

我发现最干净的解决方案是在#define ... 之前用/// @cond FOO 包围宏，在#undef 之后使用/// @endcond。感谢@Colin 为我指明了正确的方向（我只是试图理解 doxyfile 中的 cmets 所说的内容）
@Davide：你能把这个扩展成答案吗？
@einpoklum 如你所愿

【解决方案2】：

实现此目的的一种方法是使用\cond-@cond doxygen 命令：

#include <cstring>
/*! \file notes.cpp
  \brief A test for macros and doxygen
*/
/// my main function
int main ()
{
   double loc_arr[9][4][4];
   memset (loc_arr, 0.0, 144 * sizeof (double));
/// \cond DO_NOT_DOCUMENT
#define BLOCK(i) (&(loc_arr[i][0][0]))
   for (int ii = 0; ii < 9; ++ii)
   {
     memset (BLOCK(ii), double(ii), 16 * sizeof (double));
   }
#undef BLOCK
/// \endcond
   return 1;
}

【讨论】：