diff --git a/README.md b/README.md
index 15ace14..f9b69da 100644
--- a/README.md
+++ b/README.md
@@ -63,8 +63,26 @@ $browser = new Clue\React\Buzz\Browser($loop);
 $client = new Client($browser);
 ```
 
-If you need custom DNS, SSL/TLS or proxy settings, you can explicitly pass a
-custom [`Browser`](https://github.com/clue/reactphp-buzz#browser) instance.
+If you need custom connector settings (DNS resolution, TLS parameters, timeouts,
+proxy servers etc.), you can explicitly pass a custom instance of the
+[`ConnectorInterface`](https://github.com/reactphp/socket#connectorinterface)
+to the [`Browser`](https://github.com/clue/reactphp-buzz#browser) instance:
+
+```php
+$connector = new \React\Socket\Connector($loop, array(
+    'dns' => '127.0.0.1',
+    'tcp' => array(
+        'bindto' => '192.168.10.1:0'
+    ),
+    'tls' => array(
+        'verify_peer' => false,
+        'verify_peer_name' => false
+    )
+));
+
+$browser = new Browser($loop, $connector);
+$client = new Client($browser);
+```
 
 #### Promises
 
@@ -76,12 +94,15 @@ Sending requests uses a [Promise](https://github.com/reactphp/promise)-based int
 
 #### search()
 
-The `search($query, $filters = array())` method can be used to search packages matching the given query string and optionally matching the given filter parameter.
-It resolves with an array containing zero or more `Package` objects.
+The `search(string $query, array $filters = array()): PromiseInterface<Package[],Exception>` method can be used to
+search packages matching the given query string and optionally matching the given filter parameter.
+
+It resolves with an array containing zero or more [`Package`](#package) objects
+on success or rejects with an `Exception` on error.
 
 ```php
-$client->search('packagist')->then(function ($results) {
-    foreach ($results as $result) {
+$client->search('packagist')->then(function (array $packages) {
+    foreach ($packages as $package) {
         echo $package->getName() . PHP_EOL;
     }
 });
@@ -89,8 +110,11 @@ $client->search('packagist')->then(function ($results) {
 
 #### get()
 
-The `get($name)` method can be used to get package details for the given package name.
-It resolves with a single `Package` object.
+The `get(string $name): PromiseInterface<Package,Exception>` method can be used to
+get package details for the given package name.
+
+It resolves with a single [`Package`](#package) object
+on success or rejects with an `Exception` on error.
 
 ```php
 $client->get('clue/packagist-api-react')->then(function (Package $package) {
@@ -100,11 +124,14 @@ $client->get('clue/packagist-api-react')->then(function (Package $package) {
 
 #### all()
 
-The `all($filters = array())` method an be used to list all package names, optionally matching the given filter parameter.
-It resolves with an array of package names.
+The `all(array $filters = array()): PromiseInterface<string[],Exception>` method an be used to
+list all package names, optionally matching the given filter parameter.
+
+It resolves with an array of package names
+on success or rejects with an `Exception` on error.
 
 ```php
-$client->all(array('vendor' => 'clue'))->then(function ($list) {
+$client->all(array('vendor' => 'clue'))->then(function (array $names) {
     // array containing (among others) "clue/packagist-api-react"
 });
 ```
@@ -130,7 +157,7 @@ The `getDescription()` method can be used to the package description.
 The recommended way to install this library is [through Composer](https://getcomposer.org).
 [New to Composer?](https://getcomposer.org/doc/00-intro.md)
 
-This project follows [SemVer](http://semver.org/).
+This project follows [SemVer](https://semver.org/).
 This will install the latest supported version:
 
 ```bash
@@ -161,4 +188,7 @@ $ php vendor/bin/phpunit
 
 ## License
 
-MIT
+This project is released under the permissive [MIT license](LICENSE).
+
+> Did you know that I offer custom development services and issuing invoices for
+  sponsorships of releases and for contributions? Contact me (@clue) for details.
diff --git a/composer.json b/composer.json
index ae41d2b..bad0e7e 100644
--- a/composer.json
+++ b/composer.json
@@ -2,7 +2,7 @@
     "name": "clue/packagist-api-react",
     "description": "Simple async access to packagist.org's API, like listing project details, number of downloads etc., built on top of ReactPHP.",
     "keywords": ["packagist", "composer packages", "ReactPHP", "async"],
-    "homepage": "https://github.com/clue/php-packagist-api-react",
+    "homepage": "https://github.com/clue/reactphp-packagist-api",
     "license": "MIT",
     "authors": [
         {
diff --git a/src/Client.php b/src/Client.php
index 31db8d9..403b70d 100644
--- a/src/Client.php
+++ b/src/Client.php
@@ -2,9 +2,11 @@
 
 namespace Clue\React\Packagist\Api;
 
-use Packagist\Api\Result\Factory;
 use Clue\React\Buzz\Browser;
+use Packagist\Api\Result\Factory;
+use Packagist\Api\Result\Package;
 use Psr\Http\Message\ResponseInterface;
+use React\Promise\PromiseInterface;
 use Rize\UriTemplate;
 
 class Client
@@ -29,6 +31,24 @@ public function __construct(Browser $http, Factory $resultFactory = null, UriTem
         $this->uri = $uri;
     }
 
+    /**
+     * Search packages matching the given query string and optionally matching the given filter parameter.
+     *
+     * It resolves with an array containing zero or more [`Package`](#package) objects
+     * on success or rejects with an `Exception` on error.
+     *
+     * ```php
+     * $client->search('packagist')->then(function (array $packages) {
+     *     foreach ($packages as $package) {
+     *         echo $package->getName() . PHP_EOL;
+     *     }
+     * });
+     * ```
+     *
+     * @param string $query
+     * @param array  $filters
+     * @return PromiseInterface<Package[],\Exception>
+     */
     public function search($query, array $filters = array())
     {
         $filters['q'] = $query;
@@ -59,6 +79,21 @@ public function search($query, array $filters = array())
         return $fetch($url);
     }
 
+    /**
+     * Get package details for the given package name.
+     *
+     * It resolves with a single [`Package`](#package) object
+     * on success or rejects with an `Exception` on error.
+     *
+     * ```php
+     * $client->get('clue/packagist-api-react')->then(function (Package $package) {
+     *     echo $package->getDescription();
+     * });
+     * ```
+     *
+     * @param string $package
+     * @return PromiseInterface<Package,\Exception>
+     */
     public function get($package)
     {
         return $this->respond(
@@ -71,6 +106,21 @@ public function get($package)
         );
     }
 
+    /**
+     * List all package names, optionally matching the given filter parameter.
+     *
+     * It resolves with an array of package names
+     * on success or rejects with an `Exception` on error.
+     *
+     * ```php
+     * $client->all(array('vendor' => 'clue'))->then(function (array $names) {
+     *     // array containing (among others) "clue/packagist-api-react"
+     * });
+     * ```
+     *
+     * @param array $filters
+     * @return PromiseInterface<string[],\Exception>
+     */
     public function all(array $filters = array())
     {
         return $this->respond(