1 files changed, 13 insertions, 17 deletions
diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index c497871e5..2e420dc6f 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -1954,37 +1954,33 @@ function hook_xmlrpc() {
 }
 
 /**
- * Alter the definition of XML-RPC methods before they are called.
+ * Alters the definition of XML-RPC methods before they are called.
  *
- * This hook lets at module modify the callback definition for already
- * declared XML-RPC methods, when they are being invoked by a client.
+ * This hook allows modules to modify the callback definition of declared
+ * XML-RPC methods, right before they are invoked by a client. Methods may be
+ * added, or existing methods may be altered.
  *
- * This hook is invoked by xmlrpc.php. The method definitions are
- * passed in by reference. Each element of the $methods array is one
- * callback definition returned by a module from hook_xmlrpc. Additional
- * methods may be added, or existing items altered.
- *
- * Modules implementing this hook must take care of the fact that
- * hook_xmlrpc allows two distinct and incompatible formats for callback
- * definition, so module must be prepared to handle either format for
- * each callback being altered.
+ * Note that hook_xmlrpc() supports two distinct and incompatible formats to
+ * define a callback, so care must be taken when altering other methods.
  *
  * @param $methods
- *   Associative array of method callback definitions returned from
- *   hook_xmlrpc.
+ *   An asssociative array of method callback definitions, as returned from
+ *   hook_xmlrpc() implementations.
  *
  * @see hook_xmlrpc()
+ * @see xmlrpc_server()
  */
 function hook_xmlrpc_alter(&$methods) {
-
-  // Direct update for methods defined the simple way
+  // Directly change a simple method.
   $methods['drupal.login'] = 'mymodule_login';
 
-  // Lookup update for methods defined the complex way
+  // Alter complex definitions.
   foreach ($methods as $key => &$method) {
+    // Skip simple method definitions.
     if (!is_int($key)) {
       continue;
     }
+    // Perform the wanted manipulation.
     if ($method[0] == 'drupal.site.ping') {
       $method[1] = 'mymodule_directory_ping';
     }