如何在Doxygen中创建可复用的参数文档片段变量？

我在使用Doxygen编写设计文档时，每次写函数文档都要重复输入## @param session: Session -> already created session这段参数说明，重复劳动很烦。示例代码如下：

## Function which returns list of project_kpi instances based on project_kpi.kpi_type_ID
## @param session: Session -> already created session
## @param kpi: project_kpi -> project_kpi instance which must have set project_kpi.kpi_type_ID
## @return list[project_kpi] -> list of found project_kpi (results per kpi type)
## @return None -> if no results were found
## @note Not in use
def select_project_kpi_by_kpi_type(session: Session, kpi: project_kpi) -> list[project_kpi] | None: ...

想自定义一个可复用的标记（比如## @my_var_name），在任意函数文档里调用就能插入这段session参数说明，请问可行吗？怎么实现？

可行，Doxygen提供了两种高效的复用方式：

方式一：自定义宏替换重复内容 #

这是最灵活的方式，适合全局复用固定内容：

• 定义宏
  有两种定义方式可选：
  1. 修改Doxygen配置文件Doxyfile：找到PREDEFINED配置项，添加一行

     PREDEFINED += MY_SESSION_PARAM="## @param session: Session -> already created session"
     

     保存后重启Doxygen即可生效。
  2. 在代码文档中直接定义：在项目的公共文档入口或全局头文件里添加

     /** @def MY_SESSION_PARAM
         ## @param session: Session -> already created session
     */
     

• 使用宏
  在需要的函数文档里，直接用## @MY_SESSION_PARAM代替原有的重复内容即可：

  ## Function which returns list of project_kpi instances based on project_kpi.kpi_type_ID
  ## @MY_SESSION_PARAM
  ## @param kpi: project_kpi -> project_kpi instance which must have set project_kpi.kpi_type_ID
  ## @return list[project_kpi] -> list of found project_kpi (results per kpi type)
  ## @return None -> if no results were found
  ## @note Not in use
  def select_project_kpi_by_kpi_type(session: Session, kpi: project_kpi) -> list[project_kpi] | None: ...
  

方式二：用@copydoc复制已有参数说明 #

如果已经有某个函数写好了session参数的说明，可以直接复用：
比如已有函数的文档：

## @param session: Session -> already created session
def some_other_func(session: Session): ...

在目标函数文档里，用@copydoc指定要复制的参数：

## Function which returns list of project_kpi instances based on project_kpi.kpi_type_ID
## @copydoc some_other_func::session
## @param kpi: project_kpi -> project_kpi instance which must have set project_kpi.kpi_type_ID
## @return list[project_kpi] -> list of found project_kpi (results per kpi type)
## @return None -> if no results were found
## @note Not in use
def select_project_kpi_by_kpi_type(session: Session, kpi: project_kpi) -> list[project_kpi] | None: ...

这种方式不需要额外定义宏，适合复用已有参数的说明内容。

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