Блог

В чем разница между param[out] и return в Doxygen? Кажется, что они оба документируют вывод / возврат функции. Является ли разница из-за void функций, которые не имеют возвращаемого значения и только param[out] будут действительными?

Параметры 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 С другой стороны, является «входным» параметром, потому что он не изменен (и, действительно, не может быть изменен с точки зрения вызывающей функции, поскольку он передается как значение).

Вот немного более полезный и реалистичный пример:

 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] параметры предназначены только для результатов, возвращаемых с помощью параметров, а не возвращаемого значения. Вполне разумно иметь функцию, которая имеет возвращаемое значение, а также имеет необязательные возвращаемые данные, например: тот, который я только что написал, имеет подпись:

   /**
  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::stringamp; path, bool* bomWasFound=0);