Documentation for Connector

Author: clue

README.md

@@ -12,8 +12,9 @@ to google.com via a local SOCKS proxy server:
 ```php
 $loop = React\EventLoop\Factory::create();
 $client = new Client('127.0.0.1:9050', $loop);
+$connector = $client->createConnector();
 
-$client->getConnection('www.google.com:80')->then(function ($stream) {
+$connector->create('www.google.com:80')->then(function ($stream) {
     $stream->write("GET / HTTP/1.0\r\n\r\n");
 });
 
@@ -263,6 +264,24 @@ If you do not want to use authentication anymore:
 $client->unsetAuth();
 ```
 
+### Connector
+
+The `Connector` instance can be used to establish TCP connections to remote hosts.
+Each instance can be used to establish any number of TCP connections.
+
+It implements React's `ConnectorInterface` which only provides a single
+`create()` method.
+
+The `create($host, $port)` method can be used to establish a TCP
+connection to the given target host and port.
+
+It functions as an [adapter](https://en.wikipedia.org/wiki/Adapter_pattern):
+Many higher-level networking protocols build on top of TCP. It you're dealing
+with one such client implementation,  it probably uses/accepts an instance
+implementing React's `ConnectorInterface` (and usually its default `Connector`
+instance). In this case you can also pass this `Connector` instance instead
+to make this client implementation SOCKS-aware. That's it.
+
 ### Server
 
 #### Server protocol

src/Client.php

@@ -135,16 +135,46 @@ public function unsetAuth()
         $this->auth = null;
     }
 
+    /**
+     * Creates a SecureConnector instance that can be used to establish encrypted TLS connections to remote hosts.
+     *
+     * This is actually a convenience helper method that uses React's normal
+     * `SecureConnector` wrapper and this libraries' `Connector` for the
+     * underlying TCP connection.
+     *
+     * @return SecureConnector
+     * @uses self::createConnector()
+     */
     public function createSecureConnector()
     {
         return new SecureConnector($this->createConnector(), $this->loop);
     }
 
+    /**
+     * Creates a Connector instance that can be used to establish TCP connections to remote hosts.
+     *
+     * This return a new `Connector` instance which can then be used to establish
+     * any number of TCP connections.
+     *
+     * @return Connector
+     * @see Connector
+     */
     public function createConnector()
     {
         return new Connector($this);
     }
 
+    /**
+     * Should not be called directly, use createConnector() instead.
+     *
+     * This method contains the internal implementation for estasblishing a
+     * connection to the SOCKS server.
+     *
+     * @param string $host
+     * @param int    $port
+     * @return Promise Promise<Stream,Exception>
+     * @internal use self::createConnector() instead
+     */
     public function getConnection($host, $port)
     {
         if (strlen($host) > 255 || $port > 65535 || $port < 0) {
@@ -214,6 +244,17 @@ private function resolve($host)
         return $this->resolver->resolve($host);
     }
 
+    /**
+     * Internal helper used to handle the communication with the SOCKS server
+     *
+     * @param Stream      $stream
+     * @param string      $host
+     * @param int         $port
+     * @param float       $timeout
+     * @param string      $protocolVersion
+     * @param string|null $auth
+     * @return Promise Promise<stream, Exception>
+     */
     public function handleConnectedSocks(Stream $stream, $host, $port, $timeout, $protocolVersion, $auth=null)
     {
         $deferred = new Deferred();

src/Connector.php

@@ -5,6 +5,24 @@
 use React\SocketClient\ConnectorInterface;
 use Clue\React\Socks\Client;
 
+/**
+ * The Connector instance can be used to establish TCP connections to remote hosts.
+ *
+ * Each instance can be used to establish any number of TCP connections.
+ *
+ * It implements React's `ConnectorInterface` which only provides a single
+ * `create()` method.
+ *
+ * You can use this method directly in order to establish a TCP connection to
+ * the given target host and port.
+ *
+ * It functions as an adapter:
+ * Many higher-level networking protocols build on top of TCP. It you're dealing
+ * with one such client implementation,  it probably uses/accepts an instance
+ * implementing React's `ConnectorInterface` (and usually its default `Connector`
+ * instance). In this case you can also pass this `Connector` instance instead
+ * to make this client implementation SOCKS-aware. That's it.
+ */
 class Connector implements ConnectorInterface
 {
     private $client;