how do i make doxygen ignore function-like macros when building the documentation?

Question

I need to document a project with doxygen, but also need to ignore some macros, which I use for readability in small sections of my code, for which it makes no sense to appear in the documentation.

here's a minimal example (I mainly use the macros to index some C-style 2D or 3D arrays):

#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;
}

When I doxy it, with the following settings:

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

I obtain this:

Note that the only way i could avoid the macros to be documented was by setting ENABLE_PREPROCESSING = NO , which is a problem to me since it also eliminates the inclusion graph on the top of the page.

Answer 1

Option 1. You can use the preprocessor symbol DOXYGEN_SHOULD_SKIP_THIS, as described in the 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.

Option 2. You can use the EXCLUDE_SYMBOLS configuration option of doxygen.

Answer 2

One way to achieve this is to use the \cond-@cond doxygen command:

#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;
}