Doxygen-多功能单注释块 [英] Doxygen -- Single Comment Block for Multiple Functions

问题描述

您是否可以使用单个注释块来注释doxygen中的多个功能？下面是一个不起作用的简单示例。我可以做些类似的事情来获得自己想要的东西吗？

file.cpp

  #include file.h 
 
 /// @name FunsGroupedInDoxygen 
 /// @ {
 / ** 
 * @简短文档2个功能的文档
 * @param aParam A参数
 * @retval 0将始终返回
 * / 
 int fun1（int aParam）{返回0;} 
 int fun2（int aParam）{返回0;} 
 /// @} 
  

file.h

  int fun1（int aParam）; 
 int fun2（int aParam）; 
  

氧气输出：

警告：会员没有文件file.h的fun2（int aParam）（函数）。

解决方案

查看。

Are you able to use a single commenting block to comment multiple functions in doxygen? Below is a simple example that does not work. Can I do something similar to get what I want?

file.cpp

#include file.h

/// @name FunsGroupedInDoxygen
///@{
/**
 * @brief  Documentation for 2 functions
 * @param  aParam A Parameter
 * @retval 0 will always be returned
 */
int fun1(int aParam) {return 0;}
int fun2(int aParam) {return 0;}
///@}

file.h

int fun1(int aParam);
int fun2(int aParam);

Doxygen output:

warning: Member fun2(int aParam) (function) of file file.h is not documented.

解决方案

Looking at grouping in the Doxygen manual here there are several methods you can use. The one that I think best fits the situation is called Member Groups.

You can define a member group using one of two styles:

///@{ 
  ...
///@}

or

/**@{*/ 
  ... 
/**@}*/

An example of this would be:

/** @name FunctionGroup
 * @brief  Documentation for 2 functions
 * @param  aParam A Parameter
 * @retval 0 will always be returned
 */
///@{
//* fun1 specific description */
int fun1(int aParam) {return 0;}
//* fun2 specific description */
int fun2(int aParam) {return 0;}
///@}

This allows you to define a group that you can provide a generic description for and still lets you drop a comment specific to each function in the created doxygen files.

I don't have doxygen installed on the computer I'm on and can't test this code directly, however if follows the example from group2 of the member groups section on the documentation, the compiled output from that example is shown here, which hopefully is the output you desire.

Edit:

After testing the previous did work for me but only when I set the desired extraction mode to All Entities (EXTRACT_ALL = YES in the doxyfile). It would be better to only use actually documented entities so I spent some time trying a different approach from the above mentioned documentation.

file.h:

/**
 * \defgroup FunctionGroup A Group of Functions
 * @brief Documentation for 2 functions
 * @param aParam A Parameter
 * @retval 0 will always be returned
 * @{
 */ 
int fun1(int aParam);
int fun2(int aParam);
 /** @} */

file.cpp:

#include file.h

/** @ingroup FunctionGroup
 * @brief fun1 specific description
 */
 int fun1(int aParam){
    return 0;
 }
/** @ingroup FunctionGroup
 * @brief fun2 specific description
 */
 int fun2(int aParam){
    return 0;
 }

Here is an image of the output I get when I run Doxygen on those two files:

I used the doxywizard on a windows machine my doxyfile generated by this is on pastebin.

这篇关于Doxygen-多功能单注释块的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！