PHPDoc: @return void necessary?

user_66812 0
Viewed 46252

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?

phpdoc return-value php
6 Answers

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.

user_671680

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

user_26131660
Related