PHPDoc：@return需要作废？

php return-value phpdoc

2022-08-30 08:05:39

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

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

我有相当多的方法没有返回值，在注释中放置这样的东西似乎真的是多余的。把它排除在外会被认为是不好的形式吗？

答案 1

如果它为文档提供了清晰的信息，请将其保留下来，但这不是绝对必要的。这是一个完全主观的决定。

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

编辑
我站着纠正。经过一番谷歌搜索后，维基百科页面说：

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

phpdoc.org 网站说：

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

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

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

所以。。。基于此，我会说省略空白。至少这是非标准的。

答案 2

根据phpDocumentor，@return无效是有效的：

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