conditional doxygen with preprocessor that adds some arguments to a function

Question

Let's assume the following code

#include <stdio.h>
#include <stddef.h>
#include <stdint.h>

/* en/disable second arg by un/commenting */
#define B_ARG_ENABLED

/**
 * \fn add_stuff
 * \brief add stuff to stuff
 * \param a : bla bla
 //////#ifdef B_ARG_ENABLED (obviously not working)
 * \param b : blb blb
 //////#endif //B_ARG_ENABLED
 * \param c : blc blc
 * \return : some stuff
 */             
int add_stuff(int a,
#ifdef B_ARG_ENABLED
              int b,
#endif //B_ARG_ENABLED
              int c)
{
    int total = 0;
    total += a;
#ifdef B_ARG_ENABLED
    total += b;
#endif //B_ARG_ENABLED
    total += c;
    return total;
}

int main(void)
{
    printf("hello %d",add_stuff(
        1,
#ifdef B_ARG_ENABLED
        2,
#endif //B_ARG_ENABLED
        3));

    return 0;
}

I would like to have a unique doxygen header of a function but this function has a argument that is conditioned by a preprocessor variable.

Is there a way to keep a unique doxygen header?

i.e: not using two wrappers add_stuff2 and add_stuff3

Which doxygen version? I think the line `/* \fn add_stuff` should at least read `/** \fn add_stuff` as now the comment isn't really seen by doxygen. — albert, Nov 23 '21 at 10:02
all versions. if there is something possible on a version I would be happy to know about it. — Guillaume D, Nov 23 '21 at 10:05
What is the latest version you tried (won't work though), see forthcoming answer. The current version of doxygen is 1.9.2 — albert, Nov 23 '21 at 10:10

score 0 · Answer 1 · answered Nov 23 '21 at 10:18

The #if inside comments are not recognized by doxygen and so we have to use a bit of a mean approach by splitting the comment block.

/// \file

#include <stdio.h>
#include <stddef.h>
#include <stdint.h>

/* en/disable second arg by un/commenting */
//#define B_ARG_ENABLED

/**
 * add_stuff
 * \brief add stuff to stuff
 * \param a : bla bla
 */
#ifdef B_ARG_ENABLED
/**
 * \param b : blb blb
 */
#endif
/**
 * \param c : blc blc
 * \return : some stuff
 */
int add_stuff(int a,
#ifdef B_ARG_ENABLED
              int b,
#endif //B_ARG_ENABLED
              int c)
{
    int total = 0;
    total += a;
#ifdef B_ARG_ENABLED
    total += b;
#endif //B_ARG_ENABLED
    total += c;
    return total;
}

int main(void)
{
    printf("hello %d",add_stuff(
        1,
#ifdef B_ARG_ENABLED
        2,
#endif //B_ARG_ENABLED
        3));

    return 0;
}

Also the \fn should not be used here.

Marc Alff · Answer 2 · 2021-12-03T11:14:00.443

0

Possible solution, easy to maintain:

/**
  Foo.
  A contrived example.
*/
void foo(
  int a, /**< Doc for a */
  int b, /**< Doc for b */
#ifdef HAVE_FEATURE_X
  int x1, /**< Doc for x1 */
  int x2, /**< Doc for x2 */
#endif
#ifndef HAVE_FEATURE_Y
  int y1, /**< Doc for y1 */
  int y2, /**< Doc for y2 */
#endif
  int c, /**< Doc for c */
  int d  /**< Doc for d */
);

Verified with Doxygen 1.9.2

edited Dec 03 '21 at 11:14

answered Dec 02 '21 at 14:29

Marc Alff

8,227
33
59

Solution looks nice, though when defining both features I get messages about not documented variables a, b, c, d, x1 and x2 (in 2 separate messages) and also the documentation is split into 2 sections. – albert Dec 02 '21 at 15:06
@albert Correct, verified that the initial solution did not work, I should have re tested it. Now fixed with a working formatting. – Marc Alff Dec 03 '21 at 11:16

conditional doxygen with preprocessor that adds some arguments to a function

2 Answers2