Improve documentation

Author: clue

README.md

@@ -93,25 +93,27 @@ $factory = new Factory($loop, $browser);
 
 #### createClient()
 
-The `createClient($wsdl)` method can be used to download the WSDL at the
-given URL into memory and create a new [`Client`](#client).
+The `createClient(string $wsdl): PromiseInterface<Client, Exception>` method can be used to
+download the WSDL at the given URL into memory and create a new [`Client`](#client).
 
 ```php
 $factory->createClient($url)->then(
     function (Client $client) {
         // client ready
     },
     function (Exception $e) {
-        // an error occured while trying to download the WSDL
+        // an error occured while trying to download or parse the WSDL
     }
 );
 ```
 
 #### createClientFromWsdl()
 
-The `createClientFromWsdl($wsdlContents)` method works similar to `createClient()`,
-but leaves you the responsibility to load the WSDL file.
-This allows you to use local WSDL files, for instance.
+The `createClientFromWsdl(string $wsdlContents): Client` method can be used to
+create a new [`Client`](#client) from the given WSDL contents.
+
+This works similar to `createClient()`, but leaves you the responsibility to load
+the WSDL file. This allows you to use local WSDL files, for instance.
 
 ### Client
 
@@ -125,25 +127,41 @@ All public methods of the `Client` are considered *advanced usage*.
 
 #### soapCall()
 
-The `soapCall($method, $arguments)` method can be used to queue the given
-function to be sent via SOAP and wait for a response from the remote web service.
+The `soapCall(string $method, mixed[] $arguments): PromiseInterface<mixed, Exception>` method can be used to
+queue the given function to be sent via SOAP and wait for a response from the remote web service.
+
+```php
+// advanced usage, see Proxy for recommended alternative
+$promise = $client->soapCall('ping', array('hello', 42));
+```
 
 Note: This is considered *advanced usage*, you may want to look into using the [`Proxy`](#proxy) instead.
 
+```php
+$proxy = new Proxy($client);
+$promise = $proxy->ping('hello', 42);
+```
+
 #### getFunctions()
 
-The `getFunctions()` method returns an array of functions defined in the WSDL.
-It returns the equivalent of PHP's [`SoapClient::__getFunctions()`](http://php.net/manual/en/soapclient.getfunctions.php).
+The `getFunctions(): string[]` method can be used to
+return an array of functions defined in the WSDL.
+
+It returns the equivalent of PHP's 
+[`SoapClient::__getFunctions()`](http://php.net/manual/en/soapclient.getfunctions.php).
 
 #### getTypes()
 
-The `getTypes()` method returns an array of types defined in the WSDL.
-It returns the equivalent of PHP's [`SoapClient::__getTypes()`](http://php.net/manual/en/soapclient.gettypes.php).
+The `getTypes(): string[]` method can be used to
+return an array of types defined in the WSDL.
+
+It returns the equivalent of PHP's
+[`SoapClient::__getTypes()`](http://php.net/manual/en/soapclient.gettypes.php).
 
 #### getLocation()
 
-The `getLocation($function)` method can be used to return the location (URI)
-of the given webservice `$function`.
+The `getLocation(string|int $function): string` method can be used to
+return the location (URI) of the given webservice `$function`.
 
 Note that this is not to be confused with the WSDL file location.
 A WSDL file can contain any number of function definitions.
@@ -153,15 +171,18 @@ However, technically each function can potentially use a different location.
 The `$function` parameter should be a string with the the SOAP function name.
 See also [`getFunctions()`](#getfunctions) for a list of all available functions.
 
+```php
+assert('http://example.com/soap/service' === $client->getLocation('echo'));
+```
+
 For easier access, this function also accepts a numeric function index.
 It then uses [`getFunctions()`](#getfunctions) internally to get the function
 name for the given index.
 This is particularly useful for the very common case where all functions use the
 same location and accessing the first location is sufficient.
 
 ```php
-assert('http://example.com/soap/service' == $client->getLocation('echo'));
-assert('http://example.com/soap/service' == $client->getLocation(0));
+assert('http://example.com/soap/service' === $client->getLocation(0));
 ```
 
 Passing a `$function` not defined in the WSDL file will throw a `SoapFault`. 

src/Client.php

@@ -7,7 +7,17 @@
 use Clue\React\Soap\Protocol\ClientEncoder;
 use Psr\Http\Message\ResponseInterface;
 use React\Promise\Deferred;
+use React\Promise\PromiseInterface;
 
+/**
+ * The `Client` class is responsible for communication with the remote SOAP
+ * WebService server.
+ *
+ * If you want to call RPC functions, see below for the [`Proxy`](#proxy) class.
+ *
+ * Note: It's recommended (and easier) to wrap the `Client` in a [`Proxy`](#proxy) instance.
+ * All public methods of the `Client` are considered *advanced usage*.
+ */
 final class Client
 {
     private $wsdl;
@@ -40,6 +50,25 @@ public function __construct($wsdl, Browser $browser, ClientEncoder $encoder = nu
         $this->decoder = $decoder;
     }
 
+    /**
+     * Queue the given function to be sent via SOAP and wait for a response from the remote web service.
+     *
+     * ```php
+     * // advanced usage, see Proxy for recommended alternative
+     * $promise = $client->soapCall('ping', array('hello', 42));
+     * ```
+     *
+     * Note: This is considered *advanced usage*, you may want to look into using the [`Proxy`](#proxy) instead.
+     *
+     * ```php
+     * $proxy = new Proxy($client);
+     * $promise = $proxy->ping('hello', 42);
+     * ```
+     *
+     * @param string  $name
+     * @param mixed[] $args
+     * @return PromiseInterface Returns a Promise<mixed, Exception>
+     */
     public function soapCall($name, $args)
     {
         try {
@@ -55,43 +84,60 @@ public function soapCall($name, $args)
         );
     }
 
+
     /**
-     * @param ResponseInterface $response
-     * @return mixed
-     * @internal
+     * Returns an array of functions defined in the WSDL.
+     *
+     * It returns the equivalent of PHP's
+     * [`SoapClient::__getFunctions()`](http://php.net/manual/en/soapclient.getfunctions.php).
+     *
+     * @return string[]
      */
-    public function handleResponse(ResponseInterface $response)
-    {
-        return $this->decoder->decode((string)$response->getBody());
-    }
-
     public function getFunctions()
     {
         return $this->encoder->__getFunctions();
     }
 
+    /**
+     * Returns an array of types defined in the WSDL.
+     *
+     * It returns the equivalent of PHP's
+     * [`SoapClient::__getTypes()`](http://php.net/manual/en/soapclient.gettypes.php).
+     *
+     * @return string[]
+     */
     public function getTypes()
     {
         return $this->encoder->__getTypes();
     }
 
     /**
-     * get location (URI) for given function name or number
+     * Returns the location (URI) of the given webservice `$function`.
      *
      * Note that this is not to be confused with the WSDL file location.
      * A WSDL file can contain any number of function definitions.
      * It's very common that all of these functions use the same location definition.
      * However, technically each function can potentially use a different location.
      *
      * The `$function` parameter should be a string with the the SOAP function name.
-     * See also `getFunctions()` for a list of all available functions.
+     * See also [`getFunctions()`](#getfunctions) for a list of all available functions.
+     *
+     * ```php
+     * assert('http://example.com/soap/service' === $client->getLocation('echo'));
+     * ```
      *
      * For easier access, this function also accepts a numeric function index.
-     * It then uses `getFunctions()` internally to get the function
+     * It then uses [`getFunctions()`](#getfunctions) internally to get the function
      * name for the given index.
      * This is particularly useful for the very common case where all functions use the
      * same location and accessing the first location is sufficient.
      *
+     * ```php
+     * assert('http://example.com/soap/service' === $client->getLocation(0));
+     * ```
+     *
+     * Passing a `$function` not defined in the WSDL file will throw a `SoapFault`.
+     *
      * @param string|int $function
      * @return string
      * @throws \SoapFault if given function does not exist
@@ -109,4 +155,14 @@ public function getLocation($function)
         // encode request for given $function
         return (string)$this->encoder->encode($function, array())->getUri();
     }
+
+    /**
+     * @param ResponseInterface $response
+     * @return mixed
+     * @internal
+     */
+    public function handleResponse(ResponseInterface $response)
+    {
+        return $this->decoder->decode((string)$response->getBody());
+    }
 }

src/Factory.php

@@ -2,10 +2,29 @@
 
 namespace Clue\React\Soap;
 
-use React\EventLoop\LoopInterface;
 use Clue\React\Buzz\Browser;
 use Psr\Http\Message\ResponseInterface;
+use React\EventLoop\LoopInterface;
+use React\Promise\PromiseInterface;
 
+/**
+ * The `Factory` class is responsible for fetching the WSDL file once and constructing
+ * the [`Client`](#client) instance.
+ * It also registers everything with the main [`EventLoop`](https://github.com/reactphp/event-loop#usage).
+ *
+ * ```php
+ * $loop = React\EventLoop\Factory::create();
+ * $factory = new Factory($loop);
+ * ```
+ *
+ * If you need custom DNS or proxy settings, you can explicitly pass a
+ * custom [`Browser`](https://github.com/clue/php-buzz-react#browser) instance:
+ *
+ * ```php
+ * $browser = new Clue\React\Buzz\Browser($loop);
+ * $factory = new Factory($loop, $browser);
+ * ```
+ */
 final class Factory
 {
     private $loop;
@@ -20,6 +39,23 @@ public function __construct(LoopInterface $loop, Browser $browser = null)
         $this->browser = $browser;
     }
 
+    /**
+     * Downloads the WSDL at the given URL into memory and create a new [`Client`](#client).
+     *
+     * ```php
+     * $factory->createClient($url)->then(
+     *     function (Client $client) {
+     *         // client ready
+     *     },
+     *     function (Exception $e) {
+     *         // an error occured while trying to download or parse the WSDL
+     *     }
+     * );
+     * ```
+     *
+     * @param string $wsdl
+     * @return PromiseInterface Returns a Promise<Client, Exception>
+     */
     public function createClient($wsdl)
     {
         $that = $this;
@@ -29,6 +65,15 @@ public function createClient($wsdl)
         });
     }
 
+    /**
+     * Creates a new [`Client`](#client) from the given WSDL contents.
+     *
+     * This works similar to `createClient()`, but leaves you the responsibility to load
+     * the WSDL file. This allows you to use local WSDL files, for instance.
+     *
+     * @param string $wsdlContents
+     * @return Client
+     */
     public function createClientFromWsdl($wsdlContents)
     {
         $browser = $this->browser;

src/Proxy.php

@@ -2,6 +2,27 @@
 
 namespace Clue\React\Soap;
 
+use React\Promise\PromiseInterface;
+
+/**
+ * The `Proxy` class wraps an existing [`Client`](#client) instance in order to ease calling
+ * SOAP functions.
+ *
+ * ```php
+ * $proxy = new Proxy($client);
+ * ```
+ *
+ * Each and every method call to the `Proxy` class will be sent via SOAP.
+ *
+ * ```php
+ * $proxy->myMethod($myArg1, $myArg2)->then(function ($response) {
+ *     // result received
+ * });
+ * ```
+ *
+ * Please refer to your WSDL or its accompanying documentation for details
+ * on which functions and arguments are supported.
+ */
 final class Proxy
 {
     private $client;
@@ -11,6 +32,11 @@ public function __construct(Client $client)
         $this->client = $client;
     }
 
+    /**
+     * @param string  $name
+     * @param mixed[] $args
+     * @return PromiseInterface
+     */
     public function __call($name, $args)
     {
         return $this->client->soapCall($name, $args);