web-dev-qa-db-fra.com

Différence entre param [out] et retour dans doxygen?

Quelle est la différence entre \ param [out] et \ return dans Doxygen? Ils semblent tous deux documenter la sortie/le retour d'une fonction. La différence est-elle due aux fonctions void qui n'ont pas de valeur de retour et seulement param[out] serait valide?

doxygen
28
Elpezmuerto

Les paramètres de sortie sont différents des valeurs de retour. Prenez cet exemple en 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;
}

La fonction ne renvoie rien, mais la valeur à laquelle variable points est modifiée, c'est pourquoi nous l'appelons un paramètre de sortie. Il représente une "sortie" de la fonction dans la mesure où nous nous attendons à ce qu'elle soit modifiée d'une manière ou d'une autre par la fonction. val, d'autre part, est un paramètre 'input' car il n'est pas modifié (et, en effet, ne peut pas être modifié du point de vue de l'appelant de la fonction, car il est passé en tant que valeur).

Voici un exemple un peu plus utile et réaliste:

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

Dans ce cas, nous construisons un objet complexe à l'intérieur de la fonction. Nous renvoyons un simple indicateur d'état qui permet à l'utilisateur de savoir que la création de l'objet a réussi. Mais nous passons l'objet nouvellement créé en utilisant un paramètre out.

(Bien que, bien sûr, cette fonction puisse facilement renvoyer un pointeur. Certaines fonctions sont plus complexes!)

46
Daniel Buckmaster

Comme réponse plus simple, [out] les paramètres ne concernent que les résultats renvoyés via les paramètres et non la valeur de retour. Il est tout à fait raisonnable d'avoir une fonction qui a une valeur de retour et aussi des données de retour facultatives, par exemple: celle que j'écris juste a la 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);
6
Andy Dent