PHPDoc: @return void necessary?

php return-value phpdoc
Richie Marquez picture Richie Marquez · Jan 14, 2010 · Viewed 40k times · Source

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?

Answer

Jonathan Fingland picture Jonathan Fingland · Jan 14, 2010

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 page says:

@return [type description] This tag should not be used for constructors or methods defined with a void return type.

The phpdoc.org website says:

@return datatype description
@return datatype1|datatype2 description

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

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.

Related questions

Returning two values from a function

Is it possible to return two values when calling a function that would output the values? For example, I have this: <?php function ids($uid = 0, $sid = '') { $uid = 1; $sid = md5(time()); return $uid; return $sid; } echo ids(); ?> Which …

Read More
What's the difference between `return;` and no return?

Is there a difference between: function someMethod( $someArg ) { // some code return; } and function someMethod( $someArg ) { // some code // no return } Both have NULL as 'return value'. Is there a difference? Something PHP internally? Performance? Speed? edit I ask, because in Zend …

Read More
How do I check if a string contains a specific word?

Consider: $a = 'How are you?'; if ($a contains 'are') echo 'true'; Suppose I have the code above, what is the correct way to write the statement if ($a contains 'are')?

Read More