PHPDoc:@return无效是否必要? [英] PHPDoc: @return void necessary?

问题描述

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

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?

推荐答案

如果可以使文档清晰明了，则将其保留，但这不是绝对必要的.这是一个完全主观的决定.

If it makes it clear for the documentation, then leave it in, but it isn't strictly necessary. It's an entirely subjective decision.

我个人会忽略它.

编辑
我站得住了.稍作搜索后，维基百科页面说:

EDIT
I stand corrected. After a little googling, the wikipedia page says:

@return [类型描述]对于具有无效返回类型的构造函数或方法，不应使用此标记 .

phpdoc.org网站上说:

The phpdoc.org website says:

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

@return datatype description
@return datatype1|datatype2 description

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

The @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

数据类型应为有效的PHP类型(整数，字符串，布尔值等)，返回的对象类型的类名或简单地混合".如果您想显式显示多种可能的返回类型，请使用竖线将其列出，并用空格分隔(例如"@return int | string").如果在@return标记中将类名用作数据类型，则phpDocumentor将自动创建指向该类文档的链接.此外，如果函数返回多个可能的值，请使用|将它们分开.字符，并且phpDocumentor将解析出返回值中的所有类名称. phpDocumentor将显示未修改的可选描述.

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.

太...基于此，我想说的是排除空白.至少这是非标准的.

Sooo... Based on that, I would say leave out the void. It's non-standard, at least.

这篇关于PHPDoc:@return无效是否必要?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！