PHPDoc:@return void必要吗？

Question

真的有必要做这样的事情:

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

我有很多没有返回值的方法,在评论中添加这样的东西似乎很多余.将它排除在外会被认为是不好的形式吗？

Answer 1

如果它清楚地说明了文档,那么请将其保留,但这并非绝对必要.这是一个完全主观的决定.

就个人而言,我会把它留下来.

编辑
我的立场得到纠正.经过一番谷歌搜索,维基百科页面说:

@return [类型描述]此标记不应用于使用 void返回类型定义的构造函数或方法.

phpdoc.org网站说:

@return数据类型说明
@return datatype1 | datatype2 description

@return标记用于记录函数或方法的返回值.@returns是@return的别名,用于支持其他自动文档的标记格式

数据类型应该是有效的PHP类型(int,string,bool等),返回的对象类型的类名,或者只是"混合".如果要显式显示多个可能的返回类型,请列出以空格分隔的空格(例如"@return int | string").如果在@return标记中使用类名作为数据类型,phpDocumentor将自动创建指向该类文档的链接.此外,如果函数返回多个可能的值,请使用|将它们分开 character和phpDocumentor将解析返回值中的任何类名.phpDocumentor将显示未修改的可选描述.

Sooo ......基于此,我会说遗漏空白.它至少是非标准的.

Answer 2

根据phpDocumentor,@return void有效:

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

...此类型通常仅在定义方法或函数的返回类型时使用.基本定义是使用此类型指示的元素不包含值,用户不应依赖任何检索到的值.

例如:

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

在上面的示例中,未指定return语句,因此未确定返回值.

资料来源:http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html(存档页面).

Answer 3

因为我最近学到的东西,我必须编辑我的答案.

使用@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 4

从php 7.1开始，void它是有效的返回类型，可以在函数上强制执行。

我总是将其添加到docblock上。

编写它的另一个好处是void，可以将方法与可能返回任何内容但@return由于疏忽而在docblock上没有条目的方法区分开。