Question

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 1

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.