PHPDoc：@return void必要？

Question

真的有必要做這樣的事情：

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

我有沒有返回值不少方法，看來真是多餘把像這樣的評論。離開它會被認爲是不好的形式嗎？

Answer 1

如果它爲文檔明確說明，則將其保留，但並非嚴格必要。這是一個完全主觀的決定。

就我個人而言，我會放棄它。

編輯
我糾正了。一點點的谷歌搜索後，wikipedia page說：

@返回[類型說明]這個標籤不應該用於void返回類型定義的構造函數或方法使用。

的phpdoc.org網站上說：

@返回的數據類型描述
@返回datatype1 | datatype2描述

的@return標籤是用來記錄的功能或方法的返回值。 @returns是@return的別名，用於支持其他自動文檔的標記格式

數據類型應該是有效的PHP類型（int，string，bool等），返回的對象類型的類名，或者簡單地「混合」。如果要顯式顯示多個可能的返回類型，請列出它們不帶空格的管道分隔符（例如「@return int | string」）。如果在@return標記中使用類名稱作爲數據類型，phpDocumentor將自動創建一個指向該類文檔的鏈接。另外，如果函數返回多個可能的值，請使用|將它們分開字符，並且phpDocumentor將解析返回值中的任何類名稱。 phpDocumentor將顯示未修改的可選描述。

Sooo ...在此基礎上，我會說離開了虛空。至少不符合標準。

Answer 2

我必須編輯我的答案，因爲我最近學到的東西。

使用@return void代替@return null具有很特殊的含義，請考慮以下兩個PHP代碼示例。

<?php 

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

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

在第一個例子PHP實際上將返回NULL，因爲PHP總是返回NULL。但是返回的值對調用者沒有用處，因爲它沒有說明函數做了什麼。 IDE可以使用記錄的信息@return void來指示開發人員使用沒有用途的返回值。

<?php 

$foo1 = return_never(); 

$foo2 = return_sometimes(); 

第一個電話是毫無意義的，因爲變量總是包含NULL，第二個可能實際上包含的東西。如果我們把函數調用放到條件中，這會變得更加有趣。

<?php 

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

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

正如你所看到的，@return void有其使用情況，如果適用，應使用。

另請注意，它將成爲即將推出的PHP PSR-5標準的一部分。 ^[1]

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

Answer 3

據的phpDocumentor，@返回空隙是有效的：

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

... 這種類型通常僅用於定義當返回類型爲 的一種方法或函數。基本定義是用這種類型指示的元素 不包含值，並且用戶應該不依賴任何檢索到的值。

例如：

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

在上面沒有返回語句的例子中，指定並因此是不確定的 返回值。

來源：http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html（archived page）。

Answer 4

這是我如何理解和使用的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(); 
} 

Answer 5

自PHP 7.1，void is a valid return type和可以上的功能來執行。

我會總是將它添加到docblock。

編寫它的另一個好處是將void方法與可能返回任何內容的方法區分開來，但由於疏忽導致文檔塊上沒有@return條目。