参数 [out] 和返回 doxygen 之间的区别？答案

【问题标题】：Difference between param[out] and return in doxygen?参数 [out] 和返回 doxygen 之间的区别？
【发布时间】：2011-12-05 12:51:34
【问题描述】：

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

【问题讨论】：

标签： doxygen

【解决方案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 是一个“输入”参数，因为它没有被修改（实际上，从函数调用者的角度来看，它不能被修改，因为它是作为一个值传递的）。

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

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 参数传递新创建的对象。

（当然，这个函数很容易只返回一个指针。有些函数更复杂！）

【讨论】：

很好的解释。在极少数情况下，这甚至是在 Java 中完成的，其中一个对象是用输出值填充的。

【解决方案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);

【讨论】：