Разница между param [out] и возвращением в doxygen?

Question

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

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

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

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.

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

Answer 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);