$wgHooks: add closure docs & admonition to register handlers early

This patch takes Tim's advice to amend the doc block for $wgHooks with an
admonition to register hook handlers early. (This was after it was determined
that late registration of a CanonicalNamespace handler was responsible for bug
45031). Since I was already here, I also documented the use of closures with
$wgHooks, fulfilling a @TODO.

Change-Id: Id16148dbfbcc89e0365860e078e089ae541ba08f

diff --git a/includes/DefaultSettings.php b/includes/DefaultSettings.php
index 86b0849..c638f52 100644 (file)
--- a/includes/DefaultSettings.php
+++ b/includes/DefaultSettings.php
@@ -5491,17 +5491,24 @@ $wgAuth = null;
  * @endcode
  * - A function with some data:
  * @code
- *     $wgHooks['event_name'][] = array($function, $data);
+ *     $wgHooks['event_name'][] = array( $function, $data );
  * @endcode
  * - A an object method:
  * @code
- *     $wgHooks['event_name'][] = array($object, 'method');
+ *     $wgHooks['event_name'][] = array( $object, 'method' );
+ * @endcode
+ * - A closure:
+ * @code
+ *     $wgHooks['event_name'][] = function ( $hookParam ) {
+ *         // Handler code goes here.
+ *     };
  * @endcode
  *
  * @warning You should always append to an event array or you will end up
  * deleting a previous registered hook.
  *
- * @todo Does it support PHP closures?
+ * @warning Hook handlers should be registered at file scope. Registering
+ * handlers after file scope can lead to unexpected results due to caching.
  */
 $wgHooks = array();