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
Comment #1
jhodgdonYes 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.
Comment #2
TravisCarden CreditAttribution: TravisCarden commentedThanks, @jhodgdon. I submitted an issue to the code sniffer: #1519442: Add sniff for @return void