doxygen中param [out]和return之间的区别？

Question

Doxygen的\param[out]和\return有何区别？它们似乎都记录了函数的输出/返回。 void函数不具有返回值，且只有param[out]才有效？

Answer 1

输出参数与返回值不同。拿这个例子在C：

/** 
* \param[in] val  Value calculations are based off. 
* \param[out] variable Function output is written to this variable. 
* 
* \return Nothing 
*/ 
void modify_value(int val, int *variable) 
{ 
    val *= 5; 
    int working = val % 44; 
    *variable = working; 
} 

该函数返回什么，但是对其中variable点改变的价值，因此我们把它的输出参数。它表示函数的'输出'，因为我们希望函数能以某种方式对其进行修改。另一方面，val是一个'input'参数，因为它没有被修改（事实上，从函数调用者的角度来看，它不能被修改，因为它被作为一个值传递）。

这里的一个稍微更加有用和现实的例子：

typedef struct data { 
    int i; 
    int j; 
    ... 
} data; 

/** 
* \param[in] val Initialising parameter for data. 
* \param[out] dat Data pointer where the new object should be stored. 
* 
* \return True if the object was created, false if not 
*   (i.e., we're out of memory) 
*/ 
bool create_data(int val, data **dat) 
{ 
    data *newdata; 
    newdata = (data*)malloc(sizeof(data)); 
    if(newdata == NULL) 
    { 
     *dat = NULL; 
     return false; 
    } 
    newdata->i = val; 
    *dat = newdata; 
    return true; 
} 

在这种情况下，我们构造函数中的一些复杂的对象。我们返回一个简单的状态标志，让用户知道对象创建是否成功。但是我们使用out参数传出新创建的对象。

（虽然，当然，这个功能可以很容易地只返回一个指针。有些功能更复杂！）

Answer 2

作为一个简单的答案，[out]参数仅供通过参数返回而不是返回值结果。具有返回值并具有可选返回数据的功能是非常合理的，例如：我刚写的一个签名：

/** 
    Determine UTF type of a file. 
    Unless a UTF8 file has a BOM, it is regarded as unknown. 

    @param [in] path Path to file suitable for ifstream 
    @param [out] bomWasFound optional return flag to indicate a BOM was found, really only useful for UTF8 
    @return an enum indicating type, default utf_unknown 
    */ 
    UtfType CheckFileType(const std::string& path, bool* bomWasFound=0);