[DOCS] Typos, formatting, links, clarifications

Author: polyfractal

docs/configuration.asciidoc

@@ -26,7 +26,7 @@ $hosts = [
     'https://localhost',        // SSL to localhost
     'https://192.168.1.3:9200'  // SSL to IP + Port
 ];
-$client = ClientBuilder::create()              // Instantiate a new ClientBuilder
+$client = ClientBuilder::create()           // Instantiate a new ClientBuilder
                     ->setHosts($hosts)      // Set the hosts
                     ->build();              // Build the client object
 ----
@@ -44,8 +44,8 @@ $hosts = [
     'https://localhost',        // SSL to localhost
     'https://192.168.1.3:9200'  // SSL to IP + Port
 ];
-$clientBuilder = ClientBuilder::create();      // Instantiate a new ClientBuilder
-$clientBuilder->setHosts($hosts)            // Set the hosts
+$clientBuilder = ClientBuilder::create();   // Instantiate a new ClientBuilder
+$clientBuilder->setHosts($hosts);           // Set the hosts
 $client = $clientBuilder->build();          // Build the client object
 ----
 
@@ -70,14 +70,16 @@ $client = ClientBuilder::create()
 === Enabling the Logger
 Elasticsearch-PHP supports logging, but it is not enabled by default for performance reasons.  If you wish to enable logging,
 you need to select a logging implementation, install it, then enable the logger in the Client.  The recommended logger
-is https://github.com/Seldaek/monolog[Monolog], but any logger that implements the PSR/Log interface will work.
+is https://github.com/Seldaek/monolog[Monolog], but any logger that implements the `PSR/Log` interface will work.
 
 You might have noticed that Monolog was suggested during installation.  To begin using Monolog, add it to your `composer.json`:
 
 [source,json]
 ----------------------------
 {
     "require": {
+        ...
+        "elasticsearch/elasticsearch" : "~2.0",
         "monolog/monolog": "~1.0"
     }
 }
@@ -98,7 +100,7 @@ to do is provide the path to your desired logging location:
 ----
 $logger = ClientBuilder::defaultLogger('path/to/your.log');
 
-$client = ClientBuilder::create()          // Instantiate a new ClientBuilder
+$client = ClientBuilder::create()       // Instantiate a new ClientBuilder
             ->setLogger($logger)        // Set the logger with a default logger
             ->build();                  // Build the client object
 ----
@@ -107,9 +109,10 @@ You can also specify the severity of log messages that you wish to log:
 
 [source,php]
 ----
-$logger = ClientBuilder::defaultLogger('/path/to/logs/', Logger::INFO);     // set severity with second parameter
+// set severity with second parameter
+$logger = ClientBuilder::defaultLogger('/path/to/logs/', Logger::INFO);
 
-$client = ClientBuilder::create()          // Instantiate a new ClientBuilder
+$client = ClientBuilder::create()       // Instantiate a new ClientBuilder
             ->setLogger($logger)        // Set the logger with a default logger
             ->build();                  // Build the client object
 ----
@@ -126,7 +129,7 @@ use Monolog\Handler\StreamHandler;
 $logger = new Logger('name');
 $logger->pushHandler(new StreamHandler('path/to/your.log', Logger::WARNING));
 
-$client = ClientBuilder::create()          // Instantiate a new ClientBuilder
+$client = ClientBuilder::create()       // Instantiate a new ClientBuilder
             ->setLogger($logger)        // Set your custom logger
             ->build();                  // Build the client object
 ----
@@ -172,12 +175,13 @@ Connection pools are configured via the `setConnectionPool()` method:
 
 [source,php]
 ----
+$connectionPool = '\Elasticsearch\ConnectionPool\StaticNoPingConnectionPool';
 $client = ClientBuilder::create()
-            ->setConnectionPool('\Elasticsearch\ConnectionPool\StaticNoPingConnectionPool')
+            ->setConnectionPool($connectionPool)
             ->build();
 ----
 
-For more details, please see the dedicated page on link:_connection-pool.html[configuring connection pools].
+For more details, please see the dedicated page on link:_connection_pool.html[configuring connection pools].
 
 === Setting the Connection Selector
 
@@ -187,8 +191,9 @@ via the `setSelector()` method:
 
 [source,php]
 ----
+$selector = '\Elasticsearch\ConnectionPool\Selectors\StickyRoundRobinSelector';
 $client = ClientBuilder::create()
-            ->setSelector('\Elasticsearch\ConnectionPool\Selectors\StickyRoundRobinSelector')
+            ->setSelector($selector)
             ->build();
 ----
 
@@ -206,8 +211,9 @@ it can be done via the `setSerializer()` method:
 
 [source,php]
 ----
+$serializer = '\Elasticsearch\Serializers\SmartSerializer';
 $client = ClientBuilder::create()
-            ->setSerializer('\Elasticsearch\Serializers\SmartSerializer')
+            ->setSerializer($serializer)
             ->build();
 ----
 
@@ -230,10 +236,15 @@ interface.
 class MyConnectionFactory implements ConnectionFactoryInterface
 {
 
-    public function __construct($handler, array $connectionParams, SerializerInterface $serializer, LoggerInterface $logger, LoggerInterface $tracer)
+    public function __construct($handler, array $connectionParams,
+                                SerializerInterface $serializer,
+                                LoggerInterface $logger,
+                                LoggerInterface $tracer)
     {
        // Code here
     }
+
+
     /**
      * @param $hostDetails
      *
@@ -246,10 +257,16 @@ class MyConnectionFactory implements ConnectionFactoryInterface
 }
 
 
-$connectionFactory = new MyConnectionFactory($handler, $connectionParams, $serializer, $logger, $tracer);
+$connectionFactory = new MyConnectionFactory(
+    $handler,
+    $connectionParams,
+    $serializer,
+    $logger,
+    $tracer
+);
 
 $client = ClientBuilder::create()
-            ->setSerializer($connectionFactory);
+            ->setConnectionFactory($connectionFactory);
             ->build();
 ----
 

docs/connection-pool.asciidoc

@@ -1,5 +1,5 @@
 
-== The Connection Pool
+== Connection Pool
 
 The connection pool is an object inside the client that is responsible for maintaining the current list of nodes.
 Theoretically, nodes are either dead or alive.
@@ -33,7 +33,7 @@ Note that the implementation is specified via a namespace path to the class.
 === staticConnectionPool
 
 Identical to the `staticNoPingConnectionPool`, except it pings nodes before they are used to determine if they are alive.
-This may be useful for long-running scripts, but tends to be additional overhead that is unescessary for average PHP scripts.
+This may be useful for long-running scripts, but tends to be additional overhead that is unnecessary for average PHP scripts.
 
 To use the `staticConnectionPool`:
 

docs/futures.asciidoc

@@ -89,7 +89,8 @@ for ($i = 0; $i < 1000; $i++) {
 
 
 foreach ($futures as $future) {
-    echo $future['_source'];       // access future's values, causing resolution if necessary
+    // access future's values, causing resolution if necessary
+    echo $future['_source'];
 }
 ----
 
@@ -117,7 +118,8 @@ for ($i = 0; $i < 1000; $i++) {
     $futures[] = $client->get($params);     //queue up the request
 }
 
-$futures[999]->wait();    //wait() forces future resolution and will execute the underlying curl batch
+//wait() forces future resolution and will execute the underlying curl batch
+$futures[999]->wait();
 ----
 
 === Changing batch size
@@ -171,7 +173,8 @@ for ($i = 0; $i < 499; $i++) {
     $futures[] = $client->get($params);     //queue up the request
 }
 
-$body = $future[499]['body'];   // resolve the future, and therefore the underlying batch
+// resolve the future, and therefore the underlying batch
+$body = $future[499]['body'];
 ----
 
 === Heterogeneous batches are OK
@@ -226,23 +229,30 @@ $params = [
 
 $futures['searchRequest'] = $client->search($params);      // Third request
 
-$searchResults = $futures['searchRequest']['hits'];        // Resolve futures...blocks until network call completes
-$doc = $futures['getRequest']['_source'];                  // Should return immediately, since the previous future resolved the batch
+// Resolve futures...blocks until network call completes
+$searchResults = $futures['searchRequest']['hits'];
+
+// Should return immediately, since the previous future resolved the entire batch
+$doc = $futures['getRequest']['_source'];
 ----
 
 === Caveats to Future mode
 
 There are a few caveats to using future mode.  The biggest is also the most obvious: you need to deal with resolving the
-future yourself.  This is usually trivia, but can sometimes introduce unexpected complications.  For example, if you
-resolve manually using `wait()`, you may need to call `wait()` several times if there were retries.  This is because
-each retry will introduce another layer of wrapped futures, and each needs to be resolved to get the final result.
+future yourself.  This is usually trivia, but can sometimes introduce unexpected complications.
+
+For example, if you resolve manually using `wait()`, you may need to call `wait()` several times if there were retries.
+This is because each retry will introduce another layer of wrapped futures, and each needs to be resolved to get the
+final result.
 
-This is not needed if you access values via the ArrayInterface however (e.g. `$response['hits']['hits']), since
+This is not needed if you access values via the ArrayInterface however (e.g. `$response['hits']['hits']`), since
 FutureArrayInterface will automatically and fully resolve the future to provide values.
 
 Another caveat is that certain APIs will lose their "helper" functionality.  For example, "exists" APIs (e.g.
 `$client->exists()`, `$client->indices()->exists`, `$client->indices->templateExists()`, etc) typically return a true
-or false under normal operation.  When operated in future mode, the unwrapping of the future is left to your application,
+or false under normal operation.
+
+When operated in future mode, unwrapping of the future is left to your application,
 which means the client can no longer inspect the response and return a simple true/false.  Instead, you'll see the raw
 response from Elasticsearch and will have to take action appropriately.
 

docs/index.asciidoc

@@ -11,6 +11,8 @@ include::configuration.asciidoc[]
 
 include::per-request-configuration.asciidoc[]
 
+include::futures.asciidoc[]
+
 include::php_json_objects.asciidoc[]
 
 include::index-operations.asciidoc[]

docs/per-request-configuration.asciidoc

@@ -236,11 +236,11 @@ $results = $future->wait();       // resolve the future
 ----
 
 Future mode supports two options: `true` or `'lazy'`.  For more details about how asynchronous execution functions, and
-how to work with the results, see the dedicated page on link:_futures.html[Futures].
+how to work with the results, see the dedicated page on <<_future_mode>>.
 
 === SSL Encryption
 
-Normally, you will specify SSL configurations when you link:_security[create the client], since encryption typically
+Normally, you will specify SSL configurations when you create the client (see <<_security>> for more details), since encryption typically
 applies to all requests. However, it is possible to configure on a per-request basis too if you need that functionality.
 For example, if you  need to use a self-signed cert on a specific request, you can specify it via the `verify` parameter
 in the client options:

docs/selectors.asciidoc

@@ -37,6 +37,10 @@ better to "stick" to a single connection for the duration of the script.
 By default, this selector will randomize the hosts upon initialization, which will still guarantee an even distribution
 of load across the cluster.  It changes the round-robin dynamics from per-request to per-script.
 
+If you are using <<_future_mode>>, the "sticky" behavior of this selector will be non-ideal, since all parallel requests
+will go to the same node instead of multiple nodes in your cluster.  When using future mode, the default `RoundRobinSelector`
+should be preferred.
+
 If you wish to use this selector, you may do so with:
 
 [source,php]