php PHPDoc：@return void 有必要吗？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/2061550/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
PHPDoc: @return void necessary?
提问by Richie Marquez
Is it really necessary do something like this:
真的有必要做这样的事情吗：
/**
* ...
*
* @return void
*/
I have quite a few methods that don't have a return value, and it seems really redundant to put something like this in the comment. Would it be considered bad form to leave it out?
我有很多没有返回值的方法，在评论中放这样的东西似乎是多余的。将它排除在外会被认为是不好的形式吗？
回答by Jonathan Fingland
If it makes it clear for the documentation, then leave it in, but it isn't strictly necessary. It's an entirely subjective decision.
如果它对文档进行了明确说明，则将其保留，但这并不是绝对必要的。这是一个完全主观的决定。
Personally, I would leave it out.
就个人而言，我会把它排除在外。
EDIT
I stand corrected. After a little googling, the wikipedia pagesays:
编辑
我站纠正。稍微谷歌搜索后，维基百科页面说：
@return [type description] This tag should not be usedfor constructors or methods defined with a void return type.
@return [类型说明] 此标签不应用于定义为 void 返回类型的构造函数或方法。
The phpdoc.org website says:
phpdoc.org 网站说：
@return datatype description
@return datatype1|datatype2 descriptionThe @return tag is used to document the return value of functions or methods. @returns is an alias for @return to support tag formats of other automatic documentors
The datatype should be a valid PHP type(int, string, bool, etc), a class name for the type of object returned, or simply "mixed". If you want to explicitly show multiple possible return types, list them pipe-delimited without spaces (e.g. "@return int|string"). If a class name is used as the datatype in the @return tag, phpDocumentor will automatically create a link to that class's documentation. In addition, if a function returns multiple possible values, separate them using the | character, and phpDocumentor will parse out any class names in the return value. phpDocumentor will display the optional description unmodified.
@return 数据类型描述
@return datatype1|datatype2 描述@return 标签用于记录函数或方法的返回值。@returns 是@return 的别名，用于支持其他自动文档器的标签格式
数据类型应该是有效的 PHP 类型（int、string、bool 等）、返回的对象类型的类名，或者只是“混合”。如果您想显式显示多种可能的返回类型，请以竖线分隔且不带空格的方式列出它们（例如“@return int|string”）。如果在@return 标签中使用类名作为数据类型，phpDocumentor 将自动创建指向该类文档的链接。此外，如果函数返回多个可能的值，请使用 | 分隔它们。字符，并且 phpDocumentor 将解析出返回值中的任何类名。phpDocumentor 将显示未修改的可选描述。
Sooo... Based on that, I would say leave out the void. It's non-standard, at least.
Sooo...基于此，我会说忽略空白。至少，它是非标准的。
回答by tivnet
According to phpDocumentor, @return void is valid:
根据 phpDocumentor，@return void 是有效的：
http://www.phpdoc.org/docs/latest/guides/types.html#keywords
http://www.phpdoc.org/docs/latest/guides/types.html#keywords
... this type is commonly only used when defining the return type of a method or function. The basic definition is that the element indicated with this type does not contain a value and the user should not rely on any retrieved value.
For example:
/** * @return void */ function outputHello() { echo 'Hello world'; }In the example above no return statement is specified and thus is the return value not determined.
... 这种类型通常只在定义方法或函数的返回类型时使用。基本定义是用这种类型指示的元素不包含值，用户不应依赖任何检索到的值。
例如：
/** * @return void */ function outputHello() { echo 'Hello world'; }在上面的示例中，没有指定 return 语句，因此未确定返回值。
Source: http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html(archived page).
来源：http: //www.phpdoc.org/docs/latest/for-users/phpdoc/types.html（存档页面）。
回答by Fleshgrinder
I have to edit my answer because of something I have learned recently.
由于我最近学到的东西，我必须编辑我的答案。
Using @return voidinstead of @return nullhas a very special meaning, consider the following two examples of PHP code.
使用@return void代替@return null具有非常特殊的含义，请考虑以下两个 PHP 代码示例。
<?php
/**
* @return void
*/
function return_never() {
echo "foo";
}
/**
* @return null|string
*/
function return_sometimes() {
if ($this->condition()) {
return "foo";
}
}
In the first example PHP will actually return NULL, since PHP always returns NULL. But the returned value is of no use to the caller since it does not say anything about what the function did. IDEs can use the documented information of @return voidto indicate the developer that a return values is used which serves no purpose.
在第一个示例中，PHP 实际上会返回NULL，因为 PHP 总是会返回NULL。但是返回值对调用者没有用，因为它没有说明函数做了什么。IDE 可以使用 的文档化信息@return void来指示开发人员使用了无用的返回值。
<?php
$foo1 = return_never();
$foo2 = return_sometimes();
The first call is senseless since the variable will always contain NULL, the second one might actually contain something. This is becoming even more interesting if we put the function calls into a conditional.
第一个调用毫无意义，因为变量总是包含NULL，第二个调用实际上可能包含一些东西。如果我们将函数调用放入条件中，这将变得更加有趣。
<?php
if (($foo1 = return_never())) {
// Dead code
var_dump($foo1);
}
if (($foo2 = return_sometimes())) {
var_dump($foo2);
}
As you can see, @return voidhas its use cases and should be used if applicable.
如您所见，@return void有其用例，如果适用，应使用。
Also note that it is going to be a part of the upcoming PHP PSR-5 standard.[1]
另请注意，它将成为即将发布的 PHP PSR-5 标准的一部分。[1]
回答by Dimitris Baltas
As of php 7.1, voidis a valid return typeand canbe enforced on a function.
从 php 7.1 开始，它void是一个有效的返回类型，可以在函数上强制执行。
I would alwaysadd it on the docblock.
我总是将它添加到文档块中。
Another benefit of writing it, is to differentiate the voidmethods from the methods that may return anything but don't have a @returnentry on the docblock by negligence.
编写它的另一个好处是void将方法与可能返回任何内容但@return由于疏忽而在文档块上没有条目的方法区分开来。
回答by Dejv
Here is how I understand and use PhpDocumentor annotations:
以下是我理解和使用 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();
}
回答by Narrim
Personally, I think the big thing missing from this is that documenting a function returns at all is important. Currently standards dont have any documentation for functions that never return....hence a return void is way of saying yes this function does actually return.
就我个人而言，我认为这其中最重要的一点是记录函数返回值很重要。目前标准没有任何关于永不返回的函数的文档......因此返回 void 是说是这个函数确实返回的方式。
Consider this code block
考虑这个代码块
<?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()
}Clearly the use of @return at least indicates the function does return
显然，@return 的使用至少表明该函数确实返回
