Question

Doxygen中\param[out]和\return之间有什么区别？它们似乎都记录了函数的输出/返回。由于void函数没有返回值且仅param[out]有效会产生差异吗？

Answer 1

Out参数与返回值不同。以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);

param [out]和doxygen返回之间的区别？

2 个答案: