PHPDoc: @return void cần thiết?

Có thực sự cần thiết phải làm điều gì đó như thế này không:

/**
 * ...
 * 
 * @return void
 */

Tôi có khá nhiều phương thức không có giá trị trả về và có vẻ như thực sự thừa khi đặt một cái gì đó như thế này trong nhận xét. Bỏ nó ra có bị coi là hình thức xấu không?

Nếu nó làm cho tài liệu rõ ràng, thì hãy để nó vào, nhưng nó không hoàn toàn cần thiết. Đó là một quyết định hoàn toàn chủ quan.

Cá nhân, tôi sẽ bỏ nó ra.

CHỈNH SỬA
Tôi đứng đã sửa. Sau một chút googling, trang wikipedia cho biết:

@return [type description] Không nên sử dụng thẻ này cho các hàm tạo hoặc các phương thức được xác định với kiểu trả về void.

Trang web phpdoc.org cho biết:

@return datatype description
@return datatype1 | datatype2 description

Thẻ @return được sử dụng để ghi lại giá trị trả về của các hàm hoặc phương thức. @returns là bí danh của @return để hỗ trợ các định dạng thẻ của các trình tài liệu tự động khác

Kiểu dữ liệu phải là kiểu PHP hợp lệ (int, string, bool, v.v.), tên lớp cho kiểu đối tượng được trả về hoặc đơn giản là "hỗn hợp". Nếu bạn muốn hiển thị rõ ràng nhiều kiểu trả về có thể, hãy liệt kê chúng được phân cách bằng dấu sổ đứng không có dấu cách (ví dụ: "@return int | string"). Nếu tên lớp được sử dụng làm kiểu dữ liệu trong thẻ @return, phpDocumentor sẽ tự động tạo liên kết đến tài liệu của lớp đó. Ngoài ra, nếu một hàm trả về nhiều giá trị có thể, hãy phân tách chúng bằng cách sử dụng | và phpDocumentor sẽ phân tích cú pháp bất kỳ tên lớp nào trong giá trị trả về. phpDocumentor sẽ hiển thị mô tả tùy chọn chưa được sửa đổi.

Sooo ... Dựa vào đó, tôi sẽ nói rằng hãy bỏ đi khoảng trống. Nó không phải là tiêu chuẩn, ít nhất.

Theo phpDocumentor, @return void hợp lệ:

http://www.phpdoc.org/docs/latest/guides/types.html#keywords

... kiểu này thường chỉ được sử dụng khi xác định kiểu trả về của một phương thức hoặc hàm. Định nghĩa cơ bản là phần tử được chỉ ra với kiểu này không chứa giá trị và người dùng không nên dựa vào bất kỳ giá trị được truy xuất nào.

Ví dụ:

 /**
  * @return void
  */
 function outputHello()
 {
     echo 'Hello world';
 }

Trong ví dụ trên, không có câu lệnh trả về nào được chỉ định và do đó giá trị trả về không được xác định.

Nguồn: http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html ( trang lưu trữ ).

Tôi phải chỉnh sửa câu trả lời của mình vì một số điều tôi đã học được gần đây.

Sử dụng @return voidthay vì @return nullcó một ý nghĩa rất đặc biệt, hãy xem xét hai ví dụ sau về mã PHP.

<?php

/**
 * @return void
 */
function return_never() {
    echo "foo";
}

/**
 * @return null|string
 */
function return_sometimes() {
    if ($this->condition()) {
        return "foo";
    }
}

Trong ví dụ đầu tiên, PHP thực sự sẽ trả về NULL, vì PHP luôn trả về NULL. Nhưng giá trị trả về không có ích gì cho người gọi vì nó không nói gì về những gì hàm đã làm. IDE có thể sử dụng thông tin dạng văn bản @return voidđể chỉ ra cho nhà phát triển biết rằng giá trị trả về được sử dụng không phục vụ mục đích nào.

<?php

$foo1 = return_never();

$foo2 = return_sometimes();

Lần gọi đầu tiên là vô nghĩa vì biến sẽ luôn chứa NULL, lệnh thứ hai có thể thực sự chứa một cái gì đó. Điều này thậm chí còn trở nên thú vị hơn nếu chúng ta đặt các lời gọi hàm vào một điều kiện.

<?php

if (($foo1 = return_never())) {
    // Dead code
    var_dump($foo1);
}

if (($foo2 = return_sometimes())) {
    var_dump($foo2);
}

Như bạn thấy, @return voidcó các trường hợp sử dụng của nó và nên được sử dụng nếu có.

Cũng lưu ý rằng nó sẽ là một phần của chuẩn PHP PSR-5 sắp tới. ^[1]

[1] http://www.php-fig.org/psr/

Kể từ php 7.1, voidlà kiểu trả về hợp lệ và có thể được thực thi trên một hàm.

Tôi sẽ luôn thêm nó vào docblock.

Một lợi ích khác của việc viết nó là phân biệt các voidphương thức với các phương thức có thể trả về bất kỳ thứ gì nhưng không có @returnmục nhập trên docblock do sơ suất.

Đây là cách tôi hiểu và sử dụng chú thích PhpDocumentor:

<?php

/**
 * This method always returns string.
 * @return string
 */
public function useCase1()
{
    return 'foo';
}

/**
 * This method returns 2 data types so list them both using pipeline separator.
 * @return string|false
 */
public function useCase2()
{
    if ($this->foo === 1) {
        return 'foo';
    }
    return false;
}

/**
 * This method performs some operation and does not return anything so no return
 * annotation is needed.
 */
public function useCase3()
{
    $this->doOperation();
    $this->doAnotherOperation();
}

/**
 * If condition passes method returns void. If condition does not pass it returns
 * nothing so I think that specifying the return annotation with void is in space. :)
 * @return void
 */
public function useCase4()
{
    if ($this->foo === 1) {
        $this->doOperation();
        return;
    }
    $this->doAnotherOperation();
}

Cá nhân tôi nghĩ rằng điều quan trọng còn thiếu ở đây là việc ghi lại một hàm trả về là điều quan trọng. Hiện tại các tiêu chuẩn không có bất kỳ tài liệu nào cho các hàm không bao giờ trả về .... do đó, một khoảng trống trả về là cách nói có hàm này thực sự trả về.

Xem xét khối mã này

<?php

/**
 * @return void
 */
function return_void() {
    echo "foo";
}

/**
 * @return null|string
 */
function return_sometimes() {
    if ($this->condition()) {
        return "foo";
    }
}

/**
* This function actually doesnt return at all - it kills the script
**/
function noreturn() {
     //do somthing then
     die(); //or exit()
}

Rõ ràng việc sử dụng @return ít nhất cho thấy hàm không trả về