PHPDoc: @return void necessary?
PhpReturn ValuePhpdocPhp Problem Overview
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?
Php Solutions
Solution 1 - Php
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.
Solution 2 - Php
According to phpDocumentor, @return void is valid:
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.
Source: http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html (archived page).
Solution 3 - Php
I have to edit my answer because of something I have learned recently.
Using @return void
instead of @return null
has a very special meaning, consider the following two examples of PHP code.
<?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 void
to indicate the developer that a return values is used which serves no purpose.
<?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.
<?php
if (($foo1 = return_never())) {
// Dead code
var_dump($foo1);
}
if (($foo2 = return_sometimes())) {
var_dump($foo2);
}
As you can see, @return void
has its use cases and should be used if applicable.
Also note that it is going to be a part of the upcoming PHP PSR-5 standard.[1]
Solution 4 - Php
As of php 7.1, void
is a valid return type and can be enforced on a function.
I would always add it on the docblock.
Another benefit of writing it, is to differentiate the void
methods from the methods that may return anything but don't have a @return
entry on the docblock by negligence.
Solution 5 - Php
Here is how I understand and use PhpDocumentor annotations:
<?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();
}
Solution 6 - Php
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.
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