improve docs

Author: gggeek

doc/manual/phpxmlrpc_manual.adoc

@@ -688,6 +688,10 @@ $srv = new Server(array(
 ));
 ----
 
+In case a php method that you want to expose has `void` return type, given the fact that there is no such thing as "no
+return value" in the XML-RPC specification, the best approximation is to also use the class property `Value::$xmlrpcValue` to
+indicate the return type in the method signature.
+
 ==== Method handler functions [[method_handlers]]
 
 The same php function can be registered as handler of multiple xml-rpc methods.
@@ -718,9 +722,14 @@ Here is a more detailed example of what a handler function "foo" might do:
 [source, php]
 ----
 use PhpXmlRpc\PhpXmlRpc;
+use PhpXmlRpc\Request;
 use PhpXmlRpc\Response;
 use PhpXmlRpc\Value;
 
+/**
+ * @param Request $xmlrpcreq
+ * @return Response
+ */
 function foo ($xmlrpcreq)
 {
     // retrieve method name
@@ -785,12 +794,18 @@ $srv = new Server(
             "signature" => array(
                 array(Value::$xmlrpcStruct, Value::$xmlrpcInt),
                 array(Value::$xmlrpcStruct, Value::$xmlrpcInt, $xmlrpcString)
-            )
+            ),
+            "parameters_type" => "phpvals"
         )
     ),
     false
 );
-$srv->setOption(Server::OPT_FUNCTIONS_PARAMETERS_TYPE, 'phpvals');
+
+// The line below is an alternative to specifying `parameters_type` for every method in the dispatch map. It applies
+// to all php functions registered with the server.
+// If both the server option and the `parameters_type` are set, the latter takes precedence.
+//$srv->setOption(Server::OPT_FUNCTIONS_PARAMETERS_TYPE, 'phpvals');
+
 $srv->service();
 ----
 

src/Server.php

@@ -45,7 +45,7 @@ class Server
     /**
      * @var string
      * Defines how functions in $dmap will be invoked: either using an xml-rpc Request object or plain php values.
-     * Valid strings are 'xmlrpcvals', 'phpvals' or 'epivals' (only for use by polyfill-xmlrpc).
+     * Valid strings are 'xmlrpcvals', 'phpvals' or 'epivals' (the latter only for use by polyfill-xmlrpc).
      *
      * @todo create class constants for these
      */
@@ -163,7 +163,7 @@ class Server
      *                             - docstring (optional)
      *                             - signature (array, optional)
      *                             - signature_docs (array, optional)
-     *                             - parameters_type (string, optional)
+     *                             - parameters_type (string, optional). Valid values: 'phpvals', 'xmlrpcvals'
      *                             - exception_handling (int, optional)
      * @param boolean $serviceNow set to false in order to prevent the server from running upon construction
      */
@@ -710,6 +710,9 @@ public function parseRequest($data, $reqEncoding = '')
 
         $xmlRpcParser = $this->getParser();
         try {
+            // NB: during parsing, the actual type of php values built will be automatically switched from
+            // $this->functions_parameters_type to the one defined in the method signature, if defined there. This
+            // happens via the parser making a call to $this->methodNameCallback as soon as it finds the desired method
             $_xh = $xmlRpcParser->parse($data, $this->functions_parameters_type, XMLParser::ACCEPT_REQUEST, $options);
             // BC
             if (!is_array($_xh)) {