Differenza tra param [out] e return in doxygen?

Question

Qual è la differenza tra \param[out] e \return in Doxygen? Entrambi sembrano documentare l'output/il ritorno di una funzione. La differenza è dovuta alle funzioni void che non hanno un valore restituito e solo param[out] sarebbe valido?

Answer 1

I parametri di uscita sono diversi dai valori di ritorno. Facciamo un esempio in 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 funzione restituisce nulla, ma il valore a cui variable punti è cambiato, quindi chiamiamo un parametro di output. Rappresenta un "output" della funzione in quanto ci aspettiamo che sia modificato in qualche modo dalla funzione. val, d'altra parte, è un parametro 'input' perché non viene modificato (e, infatti, non può essere modificato dal punto di vista del chiamante della funzione, poiché viene passato come valore).

Ecco un esempio leggermente più utile e realistica:

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

In questo caso, si costruisce un oggetto complesso all'interno della funzione. Restituiamo un semplice flag di stato che consente all'utente di sapere che la creazione dell'oggetto ha avuto successo. Ma distribuiamo l'oggetto appena creato usando un parametro out.

(Anche se, naturalmente, questa funzione potrebbe facilmente solo restituire un puntatore. Alcune funzioni sono più complessi!)

Answer 2

come una risposta semplice, [out] parametri sono solo per i risultati restituiti tramite parametri non il valore di ritorno. È del tutto ragionevole avere una funzione che ha un valore di ritorno e ha anche i dati di ritorno opzionali, ad esempio: quella che sto solo scrivendo ha la firma:

/** 
    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);