PHPDoc：@return void 有必要吗？

Posted 2023-02-16

【中文标题】PHPDoc：@return void 有必要吗？

【英文标题】：PHPDoc: @return void necessary?

【发布时间】：2011-01-04 21:58:33

【问题描述】：

真的有必要这样做吗：

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

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

【参考方案1】：

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

就我个人而言，我会忽略它。

编辑 我站得更正了。经过一番谷歌搜索，wikipedia page 说：

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

phpdoc.org 网站说：

@return 数据类型描述 @return datatype1|datatype2 描述

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

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

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

【讨论】：

添加它有什么作用吗？如果您不记录返回类型，我相信 PHPDoc，它会自动假定 void 并将其放入文档中的方法签名中。

@Marc W：查看我的编辑。不仅没有必要，也不应该被使用。

自 2010 年以来可能发生了变化，但目前 phpdoc.org 表示：“没有return 值的函数和方法，@return 标记可以在此处省略，在这种情况下，@return 是隐含的。”

@TFennis 谢谢。我将按原样保留旧引用，但似乎 phpdoc 只是更能容忍有多少开发人员在使用它。我注意到***页面现在说[需要引用] 关于避免@return void 的声明。

从我的角度来看，这个答案已经过时了。 void 类型自 PHP 7.1 起是有效的返回类型，正如@tivnet 在下面的答案中指出的那样，根据 phpDocumentor，它也是 phpDocs 的有效类型。

【参考方案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/

【讨论】：

好点，但如果函数退出，则意味着它不会返回null。我对吗？我认为，在这种情况下，@returns void 是最好的选择。

如果您不返回任何其他内容，函数将始终返回 NULL。使用exit() 或类似的函数仍会返回NULL，但您不会收到它，因为PHP 会忽略您的代码直接跳转到关闭阶段。

有趣。我会假设，如果你说的是真的，finally 块会在我调用exit 时运行。两者之间没有直接关联，但感觉不对。谢谢你启发我。 :)

更好的措辞应该是：“[...] 仍会返回 NULL [...]”。我想我们可以将exit 与 goto 进行比较，只需告诉 PHP 停止执行当前代码并直接跳转到关闭阶段，忽略从这一点开始的任何代码（因此 goto 在比任何当前函数更外部的范围内 [global]是嵌套的）。 finally 块没有被执行，但许多其他函数被执行（例如register_shutdown、__destruct）。

这听起来更有意义，这就是我最初的想法。我还决定使用@returns void 表示该函数终止整个脚本执行，例如在HTTP 重定向中。此外，最好使用它来表示该函数并非旨在返回任何内容。

【参考方案3】：

根据 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)。

【讨论】：

这是我指出“这是正确答案”的地方。 :)

正确答案应该改成这个。

确实这是最好的答案。它也是即将推出的 PSR-5 标准的一部分。我会采用以下语义有意义的编程方法：dereuromark.de/2015/10/05/return-null-vs-return-void

【参考方案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();

【参考方案5】：

从 php 7.1 开始，void is a valid return type 和 可以在函数上强制执行。

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

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

【参考方案6】：

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