当前位置：文江博客话题详情

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

发布于 2024-12-09 04:37:19 字数 295 浏览 0 评论 0原文

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

原文

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

草莓味的萝莉 2024-12-16 04:37:19

输出参数与返回值不同。以 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;
}

函数不返回任何内容，但变量指向的值发生了变化，因此我们将其称为输出参数。它代表函数的“输出”，因为我们期望函数以某种方式修改它。另一方面，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 参数传递新创建的对象。

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

Out parameters are different from return values. Take this example in 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;
}

The function returns nothing, but the value to which variable points is changed, hence we call it an output parameter. It represents an 'output' of the function in that we expect it to be modified somehow by the function. val, on the other hand, is an 'input' parameter because it is not modified (and, indeed, cannot be modified from the perspective of the function's caller, since it is passed as a value).

Here's a slightly more useful and realistic example:

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;
}

In this case, we construct some complex object inside the function. We return a simple status flag that lets the user know the object creation was successful. But we pass out the newly-created object using an out parameter.

(Although, of course, this function could easily just return a pointer. Some functions are more complex!)

回复收藏 0 原文

往事风中埋 2024-12-16 04:37:19

作为一个更简单的答案，[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);

As a simpler answer, [out] parameters are only for results returned via parameters not the return value. It is quite reasonable to have a function which has a return value and also has optional return data, eg: one I'm just writing has the signature:

  /**
  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);

回复收藏 0 原文

~没有更多了~