Question

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

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

我有很多没有返回值的方法，在评论中添加这样的东西似乎真的很多。将它遗漏会被认为是不好的形式吗？

Answer 1

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

就个人而言，我会把它留下来。

修改
我纠正了。经过一番谷歌搜索后，wikipedia page说：

@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（archived page）。

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 is a valid return type和可以对某个函数强制执行。

我会始终将其添加到docblock上。

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

Answer 5

以下是我理解和使用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 6

就我个人而言，我认为最大的不足是记录函数的返回非常重要。当前标准没有关于永不返回的函数的任何文档。...因此，返回void表示该函数确实返回了。

考虑此代码块

<?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()
}

显然，使用@return至少表明该函数确实返回了

PHPDoc：@return void必要吗？

6 个答案: