带有预处理器的条件 doxygen，可向函数添加一些参数答案

【问题标题】：conditional doxygen with preprocessor that adds some arguments to a function带有预处理器的条件 doxygen，可向函数添加一些参数
【发布时间】：2022-01-01 19:26:11
【问题描述】：

假设下面的代码

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

我想要一个函数的唯一 doxygen 标头，但该函数的参数受预处理器变量的制约。

有没有办法保留唯一的 doxygen 标头？

即：不使用两个包装器 add_stuff2 和 add_stuff3

【问题讨论】：

哪个 doxygen 版本？我认为/* \fn add_stuff 行至少应该读为/** \fn add_stuff，因为现在doxygen 并没有真正看到该评论。
所有版本。如果某个版本有什么可能，我很乐意知道。
您尝试过的最新版本是什么（虽然不起作用），请参阅即将发布的答案。 doxygen 的当前版本是 1.9.2

标签： c doxygen preprocessor

【解决方案1】：

cmets 中的#if 不能被 doxygen 识别，因此我们不得不通过拆分评论块来使用一些卑鄙的方法。

/// \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;
}

这里也不应该使用\fn。

【讨论】：

【解决方案2】：

可能的解决方案，易于维护：

/**
  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 */
);

使用 Doxygen 1.9.2 验证

【讨论】：

解决方案看起来不错，但在定义这两个功能时，我收到有关未记录的变量 a、b、c、d、x1 和 x2 的消息（在 2 个单独的消息中），并且文档也分为 2 个部分.
@albert 正确，验证初始解决方案不起作用，我应该重新测试它。现在修复了工作格式。