2024年如何在Doxygen中实现函数参数继承？

我发现Doxygen似乎无法直接从已生成文档的函数中继承函数参数描述。比如我已经为函数f编写了完整文档：

/**
 * Add them
 * 
 * Add them
 * 
 * @param a  An integer.
 * 
 * @param b  An integer.
 * 
 * @param c  An integer.
 * 
 * @return  Return the sum.
 *
 */
int f(int a, int b, int c) { return a + b + c; }

现在我要为函数g写文档，它的a和b参数和f完全相同，之前用roxygen2+Rcpp时可以用@inheritParams f来继承参数描述：

/**
 * Do something
 * 
 * Do something
 * 
 * @inheritParams f
 * 
 * @param d  A double
 * 
 * @return  Return the result.
 * 
 */
double g(int a, int b, double d) { return (a + b) * d; }

但Doxygen没有类似的直接指令，大量复制粘贴参数描述非常繁琐，想问2024年有没有办法在Doxygen中实现这种参数继承？

可行方案 #

1. 使用@copydoc指令继承完整参数集 #

如果目标函数的部分参数和原函数完全一致，可以用@copydoc直接继承原函数的文档内容（包括参数、返回值等），之后补充或覆盖需要修改的部分：

/**
 * Do something
 * 
 * Do something
 * 
 * @copydoc f
 * @param d  A double
 * @return  Return the result.
 */
double g(int a, int b, double d) { return (a + b) * d; }

注意：@copydoc会复制原函数的所有文档内容，若目标函数的返回值与原函数不同，需要用@return指令覆盖原有描述。

2. 自定义@inheritParams指令（需配置Doxygen） #

Doxygen本身没有内置参数级继承指令，但可以通过自定义别名实现类似功能：

• 在Doxygen配置文件（Doxyfile）中添加：

  ALIASES += "inheritParams=\param[inherit]"
  

• 之后在代码文档中直接使用@inheritParams f即可继承对应函数的参数描述。此方法需依赖Doxygen 1.9.x及以上版本的自定义别名支持。

3. 用宏定义复用参数描述 #

如果只是参数描述重复，可以通过C++宏定义统一维护参数文档，再在多个函数中引用：

#define PARAM_A "@param a  An integer."
#define PARAM_B "@param b  An integer."

/**
 * Add them
 * 
 * Add them
 * 
 * PARAM_A
 * PARAM_B
 * @param c  An integer.
 * @return  Return the sum.
 */
int f(int a, int b, int c) { return a + b + c; }

/**
 * Do something
 * 
 * Do something
 * 
 * PARAM_A
 * PARAM_B
 * @param d  A double
 * @return  Return the result.
 */
double g(int a, int b, double d) { return (a + b) * d; }

这种方法无需修改Doxygen配置，兼容性强，适合参数描述固定的场景。

4. 使用分组功能统一管理通用参数 #

把重复的参数描述归类到一个分组中，再在函数文档中引用该分组：

• 先定义通用参数分组：

  /** @defgroup common_params 通用参数
   *  @{
   */
  /** @param a An integer. */
  /** @param b An integer. */
  /** @} */
  

• 然后在函数文档中引用分组：

  /**
   * Do something
   * 
   * Do something
   * 
   * @ingroup common_params
   * @param d  A double
   * @return  Return the result.
   */
  double g(int a, int b, double d) { return (a + b) * d; }
  

该方案适合多个函数共享大量通用参数的场景，便于统一修改维护。

内容的提问来源于stack exchange，提问作者user2961927