- Patch #855420 by jhodgdon, aspilicious: documentation cleanup for...

- Patch #855420 by jhodgdon, aspilicious: documentation cleanup for xmlrpcs.inc and add missing documentation headers.

includes/xmlrpcs.inc

@@ -7,9 +7,9 @@
  */
 
 /**
- * The main entry point for XML-RPC requests.
+ * Invokes XML-RPC methods on this server.
  *
- * @param $callbacks
+ * @param array $callbacks
  *   Array of external XML-RPC method names with the callbacks they map to.
  */
 function xmlrpc_server($callbacks) {
@@ -99,12 +99,13 @@ function xmlrpc_server($callbacks) {
 }
 
 /**
- * Throw an XML-RPC error.
+ * Throws an XML-RPC error.
  *
  * @param $error
- *   an error object OR integer error code
+ *   An error object or integer error code.
  * @param $message
- *   description of error, used only if integer error code was passed
+ *   (optional) The description of the error. Used only if an integer error
+ *   code was passed in.
  */
 function xmlrpc_server_error($error, $message = FALSE) {
   if ($message && !is_object($error)) {
@@ -113,6 +114,12 @@ function xmlrpc_server_error($error, $message = FALSE) {
   xmlrpc_server_output(xmlrpc_error_get_xml($error));
 }
 
+/**
+ * Sends XML-RPC output to the browser.
+ *
+ * @param string $xml
+ *   XML to send to the browser.
+ */
 function xmlrpc_server_output($xml) {
   $xml = '<?xml version="1.0"?>' . "\n" . $xml;
   drupal_add_http_header('Content-Length', strlen($xml));
@@ -122,10 +129,16 @@ function xmlrpc_server_output($xml) {
 }
 
 /**
- * Store a copy of the request temporarily.
+ * Stores a copy of an XML-RPC request temporarily.
+ *
+ * @param object $xmlrpc_server
+ *   (optional) Request object created by xmlrpc_server(). Omit to leave the
+ *   previous server object saved.
  *
- * @param $xmlrpc_server
- *   Request object created by xmlrpc_server().
+ * @return
+ *   The latest stored request.
+ *
+ * @see xmlrpc_server_get()
  */
 function xmlrpc_server_set($xmlrpc_server = NULL) {
   static $server;
@@ -135,21 +148,31 @@ function xmlrpc_server_set($xmlrpc_server = NULL) {
   return $server;
 }
 
-// Retrieve the stored request.
+/**
+ * Retrieves the latest stored XML-RPC request.
+ *
+ * @return object
+ *   The stored request.
+ *
+ * @see xmlrpc_server_set()
+ */
 function xmlrpc_server_get() {
   return xmlrpc_server_set();
 }
 
 /**
- * Dispatch the request and any parameters to the appropriate handler.
+ * Dispatches an XML-RPC request and any parameters to the appropriate handler.
+ *
+ * @param object $xmlrpc_server
+ *   Object containing information about this XML-RPC server, the methods it
+ *   provides, their signatures, etc.
+ * @param string $methodname
+ *   The external XML-RPC method name; e.g., 'system.methodHelp'.
+ * @param array $args
+ *   Array containing any parameters that are to be sent along with the request.
  *
- * @param $xmlrpc_server
- *   Contains information about this XML-RPC server, the methods it provides,
- *   their signatures, etc.
- * @param $methodname
- *   The external XML-RPC method name, e.g. 'system.methodHelp'
- * @param $args
- *   Array containing any parameters that were sent along with the request.
+ * @return
+ *   The results of the call.
  */
 function xmlrpc_server_call($xmlrpc_server, $methodname, $args) {
   // Make sure parameters are in an array
@@ -222,6 +245,20 @@ function xmlrpc_server_call($xmlrpc_server, $methodname, $args) {
   return call_user_func_array($method, $args);
 }
 
+/**
+ * Dispatches multiple XML-RPC requests.
+ *
+ * @param array $methodcalls
+ *   An array of XML-RPC requests to make. Each request is an array with the
+ *   following elements:
+ *   - methodName: Name of the method to invoke.
+ *   - params: Parameters to pass to the method.
+ *
+ * @return
+ *   An array of the results of each request.
+ *
+ * @see xmlrpc_server_call()
+ */
 function xmlrpc_server_multicall($methodcalls) {
   // See http://www.xmlrpc.com/discuss/msgReader$1208
   $return = array();
@@ -254,7 +291,12 @@ function xmlrpc_server_multicall($methodcalls) {
 }
 
 /**
+ * Lists the methods available on this XML-RPC server.
+ *
  * XML-RPC method system.listMethods maps to this function.
+ *
+ * @return array
+ *   Array of the names of methods available on this server.
  */
 function xmlrpc_server_list_methods() {
   $xmlrpc_server = xmlrpc_server_get();
@@ -262,8 +304,13 @@ function xmlrpc_server_list_methods() {
 }
 
 /**
+ * Returns a list of the capabilities of this server.
+ *
  * XML-RPC method system.getCapabilities maps to this function.
  *
+ * @return array
+ *   Array of server capabilities.
+ *
  * @see http://groups.yahoo.com/group/xml-rpc/message/2897
  */
 function xmlrpc_server_get_capabilities() {
@@ -288,16 +335,20 @@ function xmlrpc_server_get_capabilities() {
 }
 
 /**
- * XML-RPC method system.methodSignature maps to this function.
+ * Returns the method signature of a function.
  *
- * @param $methodname
- *   Name of method for which we return a method signature.
+ * This is the function mapped to the XML-RPC method system.methodSignature.
  *
- * @return
- *   An array of types representing the method signature of the
- *   function that the methodname maps to. The methodSignature of
- *   this function is 'array', 'string' because it takes an array
- *   and returns a string.
+ * A method signature is an array of the input and output types of a method. For
+ * instance, the method signature of this function is array('array', 'string'),
+ * because it takes an array and returns a string.
+ *
+ * @param string $methodname
+ *   Name of method to return a method signature for.
+ *
+ * @return array
+ *   An array of types representing the method signature of the function that
+ *   $methodname maps to.
  */
 function xmlrpc_server_method_signature($methodname) {
   $xmlrpc_server = xmlrpc_server_get();
@@ -316,10 +367,15 @@ function xmlrpc_server_method_signature($methodname) {
 }
 
 /**
+ * Returns the help for an XML-RPC method.
+ *
  * XML-RPC method system.methodHelp maps to this function.
  *
- * @param $method
+ * @param string $method
  *   Name of method for which we return a help string.
+ *
+ * @return string
+ *   Help text for $method.
  */
 function xmlrpc_server_method_help($method) {
   $xmlrpc_server = xmlrpc_server_get();