Sự khác biệt giữa param [ra] và trở lại trong doxygen?

Question

Sự khác biệt giữa \param[out] và \return trong Doxygen là gì? Cả hai đều dường như tài liệu đầu ra/trả về của một hàm. Sự khác biệt do các hàm void không có giá trị trả lại và chỉ param[out] sẽ hợp lệ?

Answer 1

Tham số ngoài khác với giá trị trả lại. Lấy ví dụ này trong 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; 
} 

Hàm này không trả về gì, nhưng giá trị mà variable được thay đổi, do đó chúng tôi gọi nó là tham số đầu ra. Nó đại diện cho một 'đầu ra' của hàm trong đó chúng ta mong đợi nó được sửa đổi bằng cách nào đó bởi hàm. Mặt khác, val là tham số 'đầu vào' vì nó không được sửa đổi (và, thực sự, không thể sửa đổi được từ quan điểm của người gọi hàm, vì nó được chuyển thành giá trị).

Dưới đây là một chút hữu dụng hơn và thực tế ví dụ:

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

Trong trường hợp này, chúng ta xây dựng một số đối tượng phức tạp bên trong hàm. Chúng tôi trả về một cờ trạng thái đơn giản cho phép người dùng biết việc tạo đối tượng đã thành công. Nhưng chúng ta vượt qua đối tượng mới được tạo ra bằng cách sử dụng tham số ngoài.

(Mặc dù, tất nhiên, chức năng này có thể dễ dàng chỉ trả về một con trỏ. Một số chức năng phức tạp hơn!)

Answer 2

Như một câu trả lời đơn giản hơn, [out] thông số chỉ dành cho kết quả trả về thông qua các thông số không phải là giá trị trả về. Khá hợp lý để có một hàm có giá trị trả về và cũng có dữ liệu trả về tùy chọn, ví dụ: một chữ tôi chỉ viết có chữ ký:

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