In most hooks we omit the reference sign & after @param.
But in some places we do use them.
We don't have standards for this.
I think the standard should be to omit them.
Do we have to add something in our standards?

Here is one example I found that uses the reference sign:
http://api.drupal.org/api/drupal/modules--node--node.api.php/function/ho...

CommentFileSizeAuthor
#5 1024684-5-remove_reference_symbol.patch13.61 KBlinclark

Comments

oriol_e9g’s picture

oriol_e9g
Primary language Catalan
Location Barcelona
commented

The pas by reference is deprecated in php 5.3, the & should be removed.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

oriol_e9g: I think the & have been mostly removed from the functions themselves. The question is that there are some docblocks saying

 *
 * @param &$foo

and we need to remove those.

aspilicious’s picture

aspilicious commented

Actually there are alot of functions still using &.
See function hook_node_access_records_alter(&$grants, $node) {

Or am I missing something...

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

You still need & if the $foo is an array, integer, string, etc. You don't need & if $foo is an object.

Anonymous’s picture

Anonymous (not verified) commented
Version: 7.x-dev » 8.x-dev
Status: Active » Needs review
StatusFileSize
new 1024684-5-remove_reference_symbol.patch13.61 KB

This removes all occurrences of reference signs in the @param parts of doc blocks. I looked at the other places were reference signs were being used and they looked legit to me.

I noticed something else while making the changes. Files like update.authorize.inc include the type of variable—for instance, * @param array $context—while other files don't. Is there a rule of thumb for when the type should be included in the @param statement? In the update.authorize.inc example, it's not like the parameter is explicitly typed in the function signature.

 * @param array $context
 *   Reference to an array used for BatchAPI storage.
 */
function update_authorize_batch_copy_project($project, $updater_name, $local_url, $filetransfer, &$context) {

If these should be changed, I'll make another issue.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Title: Omit & in @param statements? » Omit & in @param statements
Status: Needs review » Reviewed & tested by the community

Regarding @param types -- this section of the standards:
http://drupal.org/node/1354#functions
has a guideline:
"If the data type of a parameter or return value is not obvious or expected to be of a special class or interface, it is recommended to specify the data type in the @param or @return directive: [example follows]"

This standard hasn't been applied to all of Drupal by any means yet. Definitely a separate issue, but probably too big to actually tackle wholesale. So I would say leave it, at least for now.

Anyway, the patch in #5 looks good - thanks again linclark!

chx’s picture

chx commented

@oriol_e9g while call time pass-by-reference has been deprecated for a long time, that's not what's this patch is about.

dries’s picture

dries commented
Status: Reviewed & tested by the community » Fixed

Committed to 7.x and 8.x. Thanks.

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.