84

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

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

我有很多没有返回值的方法，在评论中放这样的东西似乎真的是多余的。将其排除在外会被认为是不好的形式吗？

4

6 回答 6

92

如果它使文档清楚，则将其保留，但这不是绝对必要的。这是一个完全主观的决定。

就个人而言，我会把它排除在外。

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

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

phpdoc.org 网站说：

@return 数据类型描述
@return 数据类型1|数据类型2 描述

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

数据类型应该是有效的 PHP 类型（int、string、bool 等）、返回对象类型的类名，或者简单地“混合”。如果您想显式显示多种可能的返回类型，请将它们以竖线分隔，不带空格（例如“@return int|string”）。如果在@return 标记中使用类名作为数据类型，phpDocumentor 将自动创建指向该类文档的链接。此外，如果函数返回多个可能的值，请使用 | 分隔它们。字符，并且 phpDocumentor 将解析出返回值中的任何类名。phpDocumentor 将显示未修改的可选描述。

Sooo...基于此，我会说离开空白。至少，它是非标准的。

于 2010-01-14T01:11:36.647 回答
53

根据 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 （存档页面）。

于 2013-09-30T13:14:00.173 回答
15

由于我最近学到了一些东西，我必须编辑我的答案。

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

于 2013-08-24T17:26:39.813 回答
8

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

我总是将它添加到文档块中。

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

于 2017-09-11T17:10:05.240 回答
3

以下是我理解和使用 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();
}
于 2016-02-13T15:43:17.423 回答
1

就个人而言，我认为其中缺少的重要一点是记录函数返回是很重要的。目前标准没有任何关于永远不会返回的函数的文档......因此，返回 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 的使用至少表明该函数确实返回

于 2019-10-23T03:18:13.157 回答