diff --git a/README.md b/README.md
index 54d046a9..a475b9be 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ easily be used to create a DNS server.
 * [Basic usage](#basic-usage)
 * [Caching](#caching)
   * [Custom cache adapter](#custom-cache-adapter)
-* [Resolver](#resolver)
+* [ResolverInterface](#resolverinterface)
   * [resolve()](#resolve)
   * [resolveAll()](#resolveall)
 * [Advanced usage](#advanced-usage)
@@ -111,7 +111,9 @@ $dns = $factory->createCached('8.8.8.8', $loop, $cache);
 
 See also the wiki for possible [cache implementations](https://github.com/reactphp/react/wiki/Users#cache-implementations).
 
-## Resolver
+## ResolverInterface
+
+<a id="resolver"><!-- legacy reference --></a>
 
 ### resolve()
 
diff --git a/src/Resolver/Factory.php b/src/Resolver/Factory.php
index 151807bb..4223f080 100644
--- a/src/Resolver/Factory.php
+++ b/src/Resolver/Factory.php
@@ -16,6 +16,11 @@
 
 final class Factory
 {
+    /**
+     * @param string        $nameserver
+     * @param LoopInterface $loop
+     * @return \React\Dns\Resolver\ResolverInterface
+     */
     public function create($nameserver, LoopInterface $loop)
     {
         $executor = $this->decorateHostsFileExecutor($this->createRetryExecutor($nameserver, $loop));
@@ -23,6 +28,12 @@ public function create($nameserver, LoopInterface $loop)
         return new Resolver($executor);
     }
 
+    /**
+     * @param string          $nameserver
+     * @param LoopInterface   $loop
+     * @param ?CacheInterface $cache
+     * @return \React\Dns\Resolver\ResolverInterface
+     */
     public function createCached($nameserver, LoopInterface $loop, CacheInterface $cache = null)
     {
         // default to keeping maximum of 256 responses in cache unless explicitly given
@@ -65,7 +76,7 @@ private function decorateHostsFileExecutor(ExecutorInterface $executor)
         return $executor;
     }
 
-    protected function createExecutor($nameserver, LoopInterface $loop)
+    private function createExecutor($nameserver, LoopInterface $loop)
     {
         return new TimeoutExecutor(
             new UdpTransportExecutor(
@@ -77,12 +88,12 @@ protected function createExecutor($nameserver, LoopInterface $loop)
         );
     }
 
-    protected function createRetryExecutor($namserver, LoopInterface $loop)
+    private function createRetryExecutor($namserver, LoopInterface $loop)
     {
         return new CoopExecutor(new RetryExecutor($this->createExecutor($namserver, $loop)));
     }
 
-    protected function createCachedExecutor($namserver, LoopInterface $loop, CacheInterface $cache)
+    private function createCachedExecutor($namserver, LoopInterface $loop, CacheInterface $cache)
     {
         return new CachingExecutor($this->createRetryExecutor($namserver, $loop), $cache);
     }
diff --git a/src/Resolver/Resolver.php b/src/Resolver/Resolver.php
index 87e7f34c..71a9b93a 100644
--- a/src/Resolver/Resolver.php
+++ b/src/Resolver/Resolver.php
@@ -6,9 +6,11 @@
 use React\Dns\Query\ExecutorInterface;
 use React\Dns\Query\Query;
 use React\Dns\RecordNotFoundException;
-use React\Promise\PromiseInterface;
 
-final class Resolver
+/**
+ * @see ResolverInterface for the base interface
+ */
+final class Resolver implements ResolverInterface
 {
     private $executor;
 
@@ -17,44 +19,6 @@ public function __construct(ExecutorInterface $executor)
         $this->executor = $executor;
     }
 
-    /**
-     * Resolves the given $domain name to a single IPv4 address (type `A` query).
-     *
-     * ```php
-     * $resolver->resolve('reactphp.org')->then(function ($ip) {
-     *     echo 'IP for reactphp.org is ' . $ip . PHP_EOL;
-     * });
-     * ```
-     *
-     * This is one of the main methods in this package. It sends a DNS query
-     * for the given $domain name to your DNS server and returns a single IP
-     * address on success.
-     *
-     * If the DNS server sends a DNS response message that contains more than
-     * one IP address for this query, it will randomly pick one of the IP
-     * addresses from the response. If you want the full list of IP addresses
-     * or want to send a different type of query, you should use the
-     * [`resolveAll()`](#resolveall) method instead.
-     *
-     * If the DNS server sends a DNS response message that indicates an error
-     * code, this method will reject with a `RecordNotFoundException`. Its
-     * message and code can be used to check for the response code.
-     *
-     * If the DNS communication fails and the server does not respond with a
-     * valid response message, this message will reject with an `Exception`.
-     *
-     * Pending DNS queries can be cancelled by cancelling its pending promise like so:
-     *
-     * ```php
-     * $promise = $resolver->resolve('reactphp.org');
-     *
-     * $promise->cancel();
-     * ```
-     *
-     * @param string $domain
-     * @return PromiseInterface Returns a promise which resolves with a single IP address on success or
-     *     rejects with an Exception on error.
-     */
     public function resolve($domain)
     {
         return $this->resolveAll($domain, Message::TYPE_A)->then(function (array $ips) {
@@ -62,52 +26,6 @@ public function resolve($domain)
         });
     }
 
-    /**
-     * Resolves all record values for the given $domain name and query $type.
-     *
-     * ```php
-     * $resolver->resolveAll('reactphp.org', Message::TYPE_A)->then(function ($ips) {
-     *     echo 'IPv4 addresses for reactphp.org ' . implode(', ', $ips) . PHP_EOL;
-     * });
-     *
-     * $resolver->resolveAll('reactphp.org', Message::TYPE_AAAA)->then(function ($ips) {
-     *     echo 'IPv6 addresses for reactphp.org ' . implode(', ', $ips) . PHP_EOL;
-     * });
-     * ```
-     *
-     * This is one of the main methods in this package. It sends a DNS query
-     * for the given $domain name to your DNS server and returns a list with all
-     * record values on success.
-     *
-     * If the DNS server sends a DNS response message that contains one or more
-     * records for this query, it will return a list with all record values
-     * from the response. You can use the `Message::TYPE_*` constants to control
-     * which type of query will be sent. Note that this method always returns a
-     * list of record values, but each record value type depends on the query
-     * type. For example, it returns the IPv4 addresses for type `A` queries,
-     * the IPv6 addresses for type `AAAA` queries, the hostname for type `NS`,
-     * `CNAME` and `PTR` queries and structured data for other queries. See also
-     * the `Record` documentation for more details.
-     *
-     * If the DNS server sends a DNS response message that indicates an error
-     * code, this method will reject with a `RecordNotFoundException`. Its
-     * message and code can be used to check for the response code.
-     *
-     * If the DNS communication fails and the server does not respond with a
-     * valid response message, this message will reject with an `Exception`.
-     *
-     * Pending DNS queries can be cancelled by cancelling its pending promise like so:
-     *
-     * ```php
-     * $promise = $resolver->resolveAll('reactphp.org', Message::TYPE_AAAA);
-     *
-     * $promise->cancel();
-     * ```
-     *
-     * @param string $domain
-     * @return PromiseInterface Returns a promise which resolves with all record values on success or
-     *     rejects with an Exception on error.
-     */
     public function resolveAll($domain, $type)
     {
         $query = new Query($domain, $type, Message::CLASS_IN);
diff --git a/src/Resolver/ResolverInterface.php b/src/Resolver/ResolverInterface.php
new file mode 100644
index 00000000..fe937dc7
--- /dev/null
+++ b/src/Resolver/ResolverInterface.php
@@ -0,0 +1,94 @@
+<?php
+
+namespace React\Dns\Resolver;
+
+interface ResolverInterface
+{
+    /**
+     * Resolves the given $domain name to a single IPv4 address (type `A` query).
+     *
+     * ```php
+     * $resolver->resolve('reactphp.org')->then(function ($ip) {
+     *     echo 'IP for reactphp.org is ' . $ip . PHP_EOL;
+     * });
+     * ```
+     *
+     * This is one of the main methods in this package. It sends a DNS query
+     * for the given $domain name to your DNS server and returns a single IP
+     * address on success.
+     *
+     * If the DNS server sends a DNS response message that contains more than
+     * one IP address for this query, it will randomly pick one of the IP
+     * addresses from the response. If you want the full list of IP addresses
+     * or want to send a different type of query, you should use the
+     * [`resolveAll()`](#resolveall) method instead.
+     *
+     * If the DNS server sends a DNS response message that indicates an error
+     * code, this method will reject with a `RecordNotFoundException`. Its
+     * message and code can be used to check for the response code.
+     *
+     * If the DNS communication fails and the server does not respond with a
+     * valid response message, this message will reject with an `Exception`.
+     *
+     * Pending DNS queries can be cancelled by cancelling its pending promise like so:
+     *
+     * ```php
+     * $promise = $resolver->resolve('reactphp.org');
+     *
+     * $promise->cancel();
+     * ```
+     *
+     * @param string $domain
+     * @return \React\Promise\PromiseInterface<string,\Exception>
+     *     resolves with a single IP address on success or rejects with an Exception on error.
+     */
+    public function resolve($domain);
+
+    /**
+     * Resolves all record values for the given $domain name and query $type.
+     *
+     * ```php
+     * $resolver->resolveAll('reactphp.org', Message::TYPE_A)->then(function ($ips) {
+     *     echo 'IPv4 addresses for reactphp.org ' . implode(', ', $ips) . PHP_EOL;
+     * });
+     *
+     * $resolver->resolveAll('reactphp.org', Message::TYPE_AAAA)->then(function ($ips) {
+     *     echo 'IPv6 addresses for reactphp.org ' . implode(', ', $ips) . PHP_EOL;
+     * });
+     * ```
+     *
+     * This is one of the main methods in this package. It sends a DNS query
+     * for the given $domain name to your DNS server and returns a list with all
+     * record values on success.
+     *
+     * If the DNS server sends a DNS response message that contains one or more
+     * records for this query, it will return a list with all record values
+     * from the response. You can use the `Message::TYPE_*` constants to control
+     * which type of query will be sent. Note that this method always returns a
+     * list of record values, but each record value type depends on the query
+     * type. For example, it returns the IPv4 addresses for type `A` queries,
+     * the IPv6 addresses for type `AAAA` queries, the hostname for type `NS`,
+     * `CNAME` and `PTR` queries and structured data for other queries. See also
+     * the `Record` documentation for more details.
+     *
+     * If the DNS server sends a DNS response message that indicates an error
+     * code, this method will reject with a `RecordNotFoundException`. Its
+     * message and code can be used to check for the response code.
+     *
+     * If the DNS communication fails and the server does not respond with a
+     * valid response message, this message will reject with an `Exception`.
+     *
+     * Pending DNS queries can be cancelled by cancelling its pending promise like so:
+     *
+     * ```php
+     * $promise = $resolver->resolveAll('reactphp.org', Message::TYPE_AAAA);
+     *
+     * $promise->cancel();
+     * ```
+     *
+     * @param string $domain
+     * @return \React\Promise\PromiseInterface<array,\Exception>
+     *     Resolves with all record values on success or rejects with an Exception on error.
+     */
+    public function resolveAll($domain, $type);
+}