Do we have a policy about using @return void in DocBlocks? I notice we do it exactly twice in the entire 8.x core code base.* Based on phpdoc.org it seems to be non-standard practice:

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.

The PHPDoc page on Wikipedia explicitly says, "This tag [@return] should not be used for constructors or methods defined with a void return type." What is our policy? Should there be a statement of it on the Doxygen and comment formatting conventions page? (Note to self: if we have a policy against it, a sniff for it should be added to Drupal Code Sniffer.)

* I expect both instances to be removed as part of #1109202: [meta] Fix coding standards violations across Drupal core.

Comments

jhodgdon’s picture

Status: Active » Closed (works as designed)

Yes we have a policy. If there is no return value from a function/method, we do not include the @return.
http://drupal.org/node/1354#functions

This was discussed extensively on other issues, and it is documented.

TravisCarden’s picture

Thanks, @jhodgdon. I submitted an issue to the code sniffer: #1519442: Add sniff for @return void