Разница между параметром [out] и return in 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.

(Хотя, конечно, эта функция может легко просто вернуть указатель. Некоторые функции сложнее!)

Ответ 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);