web-dev-qa-db-ja.com

param [out]とdoxygenの戻り値の違いは？

Doxygenでの \ param [out] と \ return の違いは何ですか？どちらも関数の出力/戻り値を文書化しているようです。 void関数が戻り値を持たず、param[out]は有効ですか？

doxygen
28
Elpezmuerto

出力パラメーターは戻り値とは異なります。 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パラメーターを使用して、新しく作成されたオブジェクトを渡します。

（もちろん、この関数は簡単にポインタを返すだけでした。より複雑な関数もあります！）

46
Daniel Buckmaster

より簡単な答えとして、[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);
6
Andy Dent