Annotate the unusual use of "$callback()" in "xsprintf()"

Summary: Ref T13588. See D21500. This syntax is unusual and there are some hidden complexities involved; annotate them. See D21500 for more discussion.

Test Plan: Read text, reviewed D21500.

Maniphest Tasks: T13588

Differential Revision: https://secure.phabricator.com/D21541

src/xsprintf/xsprintf.php

@@ -67,6 +67,18 @@ function xsprintf($callback, $userdata, array $argv) {
         }
 
         if ($callback !== null) {
+
+          // See T13588 and D21500. This function uses "$callback()", instead
+          // of "call_user_func()", to simplify reference behavior: some of
+          // these arguments must be passed by reference.
+
+          // Prior to PHP7, this syntax will not work if "$callback" is a
+          // string referencing a static method, like "C::m".
+
+          // This syntax does work if "$callback" is an array referencing
+          // a static method, like "array('C', 'm')", in all versions of PHP
+          // since PHP 5.4.
+
           $callback($userdata, $pattern, $pos, $argv[$arg], $len);
         }
       }