Move api docs to phpdoc (wip); fix wrong property name in Response class

[plcapi.git] / src / Value.php

diff --git a/src/Value.php b/src/Value.php
index f0d331a..c9fc614 100644 (file)
--- a/src/Value.php
+++ b/src/Value.php
@@ -4,6 +4,9 @@ namespace PhpXmlRpc;
 
 use PhpXmlRpc\Helper\Charset;
 
+/**
+ * This class enables the creation and encapsulation of values for XML-RPC.
+ */
 class Value implements \Countable, \IteratorAggregate, \ArrayAccess
 {
     public static $xmlrpcI4 = "i4";
@@ -38,10 +41,14 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
 
     /**
      * Build an xmlrpc value.
-     * When no value or type is passed in, the value is left uninitialized, and the value can be added later
      *
-     * @param mixed $val
-     * @param string $type any valid xmlrpc type name (lowercase). If null, 'string' is assumed
+     * When no value or type is passed in, the value is left uninitialized, and the value can be added later.
+     *
+     * @param mixed $val if passing in an array, all array elements should be PhpXmlRpc\Value themselves
+     * @param string $type any valid xmlrpc type name (lowercase): i4, int, boolean, string, double, dateTime.iso8601,
+     *                     base64, array, struct, null.
+     *                     If null, 'string' is assumed.
+     *                     You should refer to http://www.xmlrpc.com/spec for more information on what each of these mean.
      */
     public function __construct($val = -1, $type = '')
     {
@@ -79,10 +86,14 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     }
 
     /**
-     * Add a single php value to an (uninitialized) xmlrpc value.
+     * Add a single php value to an xmlrpc value.
+     *
+     * If the xmlrpc value is an array, the php value is added as its last element.
+     * If the xmlrpc value is empty (uninitialized), this method makes it a scalar value, and sets that value.
+     * Fails if the xmlrpc value is not an array and already initialized.
      *
      * @param mixed $val
-     * @param string $type
+     * @param string $type allowed values: i4, int, boolean, string, double, dateTime.iso8601, base64, null.
      *
      * @return int 1 or 0 on failure
      */
@@ -131,7 +142,11 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     }
 
     /**
-     * Add an array of xmlrpc values objects to an xmlrpc value.
+     * Add an array of xmlrpc value objects to an xmlrpc value.
+     *
+     * If the xmlrpc value is an array, the elements are appended to the existing ones.
+     * If the xmlrpc value is empty (uninitialized), this method makes it an array value, and sets that value.
+     * Fails otherwise.
      *
      * @param Value[] $values
      *
@@ -158,7 +173,11 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     }
 
     /**
-     * Add an array of named xmlrpc value objects to an xmlrpc value.
+     * Merges an array of named xmlrpc value objects into an xmlrpc value.
+     *
+     * If the xmlrpc value is a struct, the elements are merged with the existing ones (overwriting existing ones).
+     * If the xmlrpc value is empty (uninitialized), this method makes it a struct value, and sets that value.
+     * Fails otherwise.
      *
      * @param Value[] $values
      *
@@ -185,7 +204,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     }
 
     /**
-     * Returns a string containing "struct", "array", "scalar" or "undef" describing the base type of the value.
+     * Returns a string containing either "struct", "array", "scalar" or "undef", describing the base type of the value.
      *
      * @return string
      */
@@ -298,7 +317,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     }
 
     /**
-     * Returns xml representation of the value. XML prologue not included.
+     * Returns the xml representation of the value. XML prologue not included.
      *
      * @param string $charsetEncoding the charset to be used for serialization. if null, US-ASCII is assumed
      *
@@ -318,6 +337,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
 
     /**
      * Checks whether a struct member with a given name is present.
+     *
      * Works only on xmlrpc values of type struct.
      *
      * @param string $key the name of the struct member to be looked up
@@ -368,7 +388,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     }
 
     /**
-     * Returns the value of a scalar xmlrpc value.
+     * Returns the value of a scalar xmlrpc value (base 64 decoding is automatically handled here)
      *
      * @return mixed
      */
@@ -382,6 +402,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
 
     /**
      * Returns the type of the xmlrpc value.
+     *
      * For integers, 'int' is always returned in place of 'i4'.
      *
      * @return string
@@ -398,7 +419,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     }
 
     /**
-     * Returns the m-th member of an xmlrpc value of struct type.
+     * Returns the m-th member of an xmlrpc value of array type.
      *
      * @param integer $key the index of the value to be retrieved (zero based)
      *
@@ -438,8 +459,8 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess
     /**
      * Returns the number of members in an xmlrpc value:
      * - 0 for uninitialized values
-     * - 1 for scalars
-     * - the number of elements for structs and arrays
+     * - 1 for scalar values
+     * - the number of elements for struct and array values
      *
      * @return integer
      */