Description:
------------
I'm reporting a documentation comment that was rejected but should be valid.

note 87076 rejected and deleted from language.references.return by notes editor danbrown

----- Copy of your note below -----

"Do not use return-by-reference to increase performance"

This is not accurate.  If you want PHP to return a string that was passed-by-reference without making a copy of it then you must also return-by-reference to increase performance.

Robert Chapin
Chapin Information Services

Reproduce code:
---------------
$a = 'world';
$b = escape($a);
$b .= '3';
echo $a;

function escape(&$hello) {
  $hello .= '2';
  return $hello;
}

Expected result:
----------------
world23

Actual result:
--------------
world2