- Patch #855418 by jhodgdon, aspilicious: fix doc errors in xmlcpr.inc and fill in the missing doc headers.

1 files changed, 132 insertions, 47 deletions

diff --git a/includes/xmlrpc.inc b/includes/xmlrpc.inc
index fd2266d70..ac874d470 100644
--- a/includes/xmlrpc.inc
+++ b/includes/xmlrpc.inc
@@ -13,14 +13,15 @@
  */
 
 /**
- * Turn a data structure into objects with 'data' and 'type' attributes.
+ * Turns a data structure into objects with 'data' and 'type' attributes.
  *
  * @param $data
  *   The data structure.
  * @param $type
- *   Optional type assign to $data.
- * @return
- *   Object.
+ *   Optional type to assign to $data.
+ *
+ * @return object
+ *   An XML-RPC data object containing the input $data.
  */
 function xmlrpc_value($data, $type = FALSE) {
   $xmlrpc_value = new stdClass();
@@ -44,16 +45,19 @@ function xmlrpc_value($data, $type = FALSE) {
 }
 
 /**
- * Map PHP type to XML-RPC type.
+ * Maps a PHP type to an XML-RPC type.
  *
  * @param $xmlrpc_value
  *   Variable whose type should be mapped.
- * @return
- *   XML-RPC type as string.
+ *
+ * @return string
+ *   The corresponding XML-RPC type.
+ *
  * @see http://www.xmlrpc.com/spec#scalars
  */
 function xmlrpc_value_calculate_type($xmlrpc_value) {
-  // http://www.php.net/gettype: Never use gettype() to test for a certain type [...] Instead, use the is_* functions.
+  // http://www.php.net/gettype: Never use gettype() to test for a certain type
+  // [...] Instead, use the is_* functions.
   if (is_bool($xmlrpc_value->data)) {
     return 'boolean';
   }
@@ -82,12 +86,13 @@ function xmlrpc_value_calculate_type($xmlrpc_value) {
 }
 
 /**
- * Generate XML representing the given value.
+ * Generates XML representing the given value.
  *
  * @param $xmlrpc_value
  *   A value to be represented in XML.
+ *
  * @return
- *   XML representation of value.
+ *   XML representation of $xmlrpc_value.
  */
 function xmlrpc_value_get_xml($xmlrpc_value) {
   switch ($xmlrpc_value->type) {
@@ -133,12 +138,15 @@ function xmlrpc_value_get_xml($xmlrpc_value) {
 }
 
 /**
- * Construct an object representing an XML-RPC message.
+ * Constructs an object representing an XML-RPC message.
  *
  * @param $message
- *   String containing XML as defined at http://www.xmlrpc.com/spec
- * @return
- *   Object
+ *   A string containing an XML message.
+ *
+ * @return object
+ *   An XML-RPC object containing the message.
+ *
+ * @see http://www.xmlrpc.com/spec
  */
 function xmlrpc_message($message) {
   $xmlrpc_message = new stdClass();
@@ -156,9 +164,10 @@ function xmlrpc_message($message) {
  * object.
  *
  * @param $xmlrpc_message
- *   Object generated by xmlrpc_message()
+ *   An object generated by xmlrpc_message().
+ *
  * @return
- *   TRUE if parsing succeeded; FALSE otherwise
+ *   TRUE if parsing succeeded; FALSE otherwise.
  */
 function xmlrpc_message_parse($xmlrpc_message) {
   $xmlrpc_message->_parser = xml_parser_create();
@@ -186,12 +195,15 @@ function xmlrpc_message_parse($xmlrpc_message) {
 }
 
 /**
- * Store a copy of the $xmlrpc_message object temporarily.
+ * Stores a copy of the most recent XML-RPC message object temporarily.
  *
  * @param $value
- *   Object
- * @return
- *   The most recently stored $xmlrpc_message
+ *   An XML-RPC message to store, or NULL to keep the last message.
+ *
+ * @return object
+ *   The most recently stored message.
+ *
+ * @see xmlrpc_message_get()
  */
 function xmlrpc_message_set($value = NULL) {
   static $xmlrpc_message;
@@ -201,10 +213,21 @@ function xmlrpc_message_set($value = NULL) {
   return $xmlrpc_message;
 }
 
+/**
+ * Returns the most recently stored XML-RPC message object.
+ *
+ * @return object
+ *   The most recently stored message.
+ *
+ * @see xmlrpc_message_set()
+ */
 function xmlrpc_message_get() {
   return xmlrpc_message_set();
 }
 
+/**
+ * Handles opening tags for XML parsing in xmlrpc_message_parse().
+ */
 function xmlrpc_message_tag_open($parser, $tag, $attr) {
   $xmlrpc_message = xmlrpc_message_get();
   $xmlrpc_message->current_tag_contents = '';
@@ -228,12 +251,18 @@ function xmlrpc_message_tag_open($parser, $tag, $attr) {
   xmlrpc_message_set($xmlrpc_message);
 }
 
+/**
+ * Handles character data for XML parsing in xmlrpc_message_parse().
+ */
 function xmlrpc_message_cdata($parser, $cdata) {
   $xmlrpc_message = xmlrpc_message_get();
   $xmlrpc_message->current_tag_contents .= $cdata;
   xmlrpc_message_set($xmlrpc_message);
 }
 
+/**
+ * Handles closing tags for XML parsing in xmlrpc_message_parse().
+ */
 function xmlrpc_message_tag_close($parser, $tag) {
   $xmlrpc_message = xmlrpc_message_get();
   $value_flag = FALSE;
@@ -314,14 +343,15 @@ function xmlrpc_message_tag_close($parser, $tag) {
 }
 
 /**
- * Construct an object representing an XML-RPC request
+ * Constructs an object representing an XML-RPC request.
  *
  * @param $method
- *   The name of the method to be called
+ *   The name of the method to be called.
  * @param $args
  *   An array of parameters to send with the method.
- * @return
- *   Object
+ *
+ * @return object
+ *   An XML-RPC object representing the request.
  */
 function xmlrpc_request($method, $args) {
   $xmlrpc_request = new stdClass();
@@ -344,7 +374,20 @@ EOD;
   return $xmlrpc_request;
 }
 
-
+/**
+ * Generates, temporarily saves, and returns an XML-RPC error object.
+ *
+ * @param $code
+ *   The error code.
+ * @param $message
+ *   The error message.
+ * @param $reset
+ *   TRUE to empty the temporary error storage. Ignored if $code is supplied.
+ *
+ * @return object
+ *   An XML-RPC error object representing $code and $message, or the most
+ *   recently stored error object if omitted.
+ */
 function xmlrpc_error($code = NULL, $message = NULL, $reset = FALSE) {
   static $xmlrpc_error;
   if (isset($code)) {
@@ -359,6 +402,15 @@ function xmlrpc_error($code = NULL, $message = NULL, $reset = FALSE) {
   return $xmlrpc_error;
 }
 
+/**
+ * Converts an XML-RPC error object into XML.
+ *
+ * @param $xmlrpc_error
+ *   The XML-RPC error object.
+ *
+ * @return string
+ *   An XML representation of the error as an XML methodResponse.
+ */
 function xmlrpc_error_get_xml($xmlrpc_error) {
   return <<<EOD
 <methodResponse>
@@ -381,6 +433,15 @@ function xmlrpc_error_get_xml($xmlrpc_error) {
 EOD;
 }
 
+/**
+ * Converts a PHP or ISO date/time to an XML-RPC object.
+ *
+ * @param $time
+ *   A PHP timestamp or an ISO date-time string.
+ *
+ * @return object
+ *   An XML-RPC time/date object.
+ */
 function xmlrpc_date($time) {
   $xmlrpc_date = new stdClass();
   $xmlrpc_date->is_date = TRUE;
@@ -407,10 +468,28 @@ function xmlrpc_date($time) {
   return $xmlrpc_date;
 }
 
+/**
+ * Converts an XML-RPC date-time object into XML.
+ *
+ * @param $xmlrpc_date
+ *   The XML-RPC date-time object.
+ *
+ * @return string
+ *   An XML representation of the date/time as XML.
+ */
 function xmlrpc_date_get_xml($xmlrpc_date) {
   return '<dateTime.iso8601>' . $xmlrpc_date->year . $xmlrpc_date->month . $xmlrpc_date->day . 'T' . $xmlrpc_date->hour . ':' . $xmlrpc_date->minute . ':' . $xmlrpc_date->second . '</dateTime.iso8601>';
 }
 
+/**
+ * Returns an XML-RPC base 64 object.
+ *
+ * @param $data
+ *   Base 64 data to store in returned object.
+ *
+ * @return object
+ *   An XML-RPC base 64 object.
+ */
 function xmlrpc_base64($data) {
   $xmlrpc_base64 = new stdClass();
   $xmlrpc_base64->is_base64 = TRUE;
@@ -418,34 +497,38 @@ function xmlrpc_base64($data) {
   return $xmlrpc_base64;
 }
 
+/**
+ * Converts an XML-RPC base 64 object into XML.
+ *
+ * @param $xmlrpc_base64
+ *   The XML-RPC base 64 object.
+ *
+ * @return string
+ *   An XML representation of the base 64 data as XML.
+ */
 function xmlrpc_base64_get_xml($xmlrpc_base64) {
   return '<base64>' . base64_encode($xmlrpc_base64->data) . '</base64>';
 }
 
 /**
- * Performs one or more XML-RPC request(s).
+ * Performs one or more XML-RPC requests.
  *
  * @param $url
- *   An absolute URL of the XML-RPC endpoint.
- *     Example:
- *     http://www.example.com/xmlrpc.php
+ *   The absolute URL of the XML-RPC endpoint. Example:
+ *   http://www.example.com/xmlrpc.php
  * @param ...
- *   For one request:
- *     The method name followed by a variable number of arguments to the
- *     method.
- *   For multiple requests (system.multicall):
- *     An array of call arrays. Each call array follows the pattern of the
- *     single request: method name followed by the arguments to the method.
- * @return
- *   Either the return value of the method on success, or FALSE.  If FALSE is
- *   returned, see xmlrpc_errno() and xmlrpc_error_msg().
- *   - For a non-multicall request: the result just as if this had been a local
- *     function call.
- *   - For a multicall request: an array of results. Each result will either be
- *     a one-element array containing the result returned by the method called,
- *     or an xmlrpc_error object if the call failed.
+ *   - For one request: The method name followed by a variable number of
+ *     arguments to the method.
+ *   - For multiple requests (system.multicall): An array of call arrays. Each
+ *     call array follows the pattern of the single request: method name
+ *     followed by the arguments to the method.
  *
- * @see xmlrpc_error()
+ * @return
+ *   A single response (single request) or an array of responses (multicall
+ *   request). Each response is the return value of the method, just as if it
+ *   has been a local function call, on success, or FALSE on failure. If FALSE
+ *   is returned, see xmlrpc_errno() and xmlrpc_error_msg() to get more
+ *   information.
  */
 function _xmlrpc() {
   $args = func_get_args();
@@ -505,7 +588,7 @@ function _xmlrpc() {
 }
 
 /**
- * Returns the last XML-RPC client error number
+ * Returns the last XML-RPC client error number.
  */
 function xmlrpc_errno() {
   $error = xmlrpc_error();
@@ -513,7 +596,7 @@ function xmlrpc_errno() {
 }
 
 /**
- * Returns the last XML-RPC client error message
+ * Returns the last XML-RPC client error message.
  */
 function xmlrpc_error_msg() {
   $error = xmlrpc_error();
@@ -521,7 +604,9 @@ function xmlrpc_error_msg() {
 }
 
 /**
- * Clears any previous error.
+ * Clears any previously-saved errors.
+ *
+ * @see xmlrpc_error()
  */
 function xmlrpc_clear_error() {
   xmlrpc_error(NULL, NULL, TRUE);