Missing docs (#5391)

Various documentation improvements.

vertx-core/src/main/asciidoc/http.adoc

@@ -1672,7 +1672,7 @@ fairness of the distribution of the client requests over the connections to the
 HTTP/2 advocates to use a single connection to a server, by default the http client uses a single
 connection for each server, all the streams to the same server are multiplexed over the same connection.
 
-When the clients needs to use more than a single connection and use pooling, the {@link io.vertx.core.http.PoolOptions#setHttp2MaxSize(int)}
+When the client needs to use more than a single connection and use pooling, the {@link io.vertx.core.http.PoolOptions#setHttp2MaxSize(int)}
 shall be used.
 
 When it is desirable to limit the number of multiplexed streams per connection and use a connection
@@ -1694,7 +1694,7 @@ or close the client instance.
 Alternatively you can set idle timeout using {@link io.vertx.core.http.HttpClientOptions#setIdleTimeout(int)} - any
 connections not used within this timeout will be closed. Please note the idle timeout value is in seconds not milliseconds.
 
-==== Un-pooled client connections
+=== Un-pooled client connections
 
 Most HTTP interactions are performed using {@code HttpClientAgent} request/response API: the client obtains
 a connection from its pool of connections to perform a request.

vertx-core/src/main/asciidoc/index.adoc

@@ -566,7 +566,7 @@ It's very common in Vert.x to want to perform an action after a delay, or period
 
 In standard verticles you can't just make the thread sleep to introduce a delay, as that will block the event loop thread.
 
-Instead you use Vert.x timers. Timers can be *one-shot* or *periodic*. We'll discuss both
+Instead, you use Vert.x timers. Timers can be *one-shot* or *periodic*. We'll discuss both
 
 ==== One-shot Timers
 
@@ -611,6 +611,17 @@ To cancel a periodic timer, call {@link io.vertx.core.Vertx#cancelTimer} specify
 {@link examples.CoreExamples#example17}
 ----
 
+==== Timer as a Future
+
+{@link io.vertx.core.Timer} combines one-shot timer and {@link {@link io.vertx.core.Future} in a single API.
+
+[source,$lang]
+----
+{@link examples.CoreExamples#timerExample}
+----
+
+The future succeeds when the timer fires, conversely {@link io.vertx.core.Timer#cancel() cancelling} the timer fails the future.
+
 ==== Automatic clean-up in verticles
 
 If you're creating timers from inside verticles, those timers will be automatically closed

vertx-core/src/main/java/examples/CoreExamples.java

@@ -388,6 +388,20 @@ public void example17(Vertx vertx, long timerID) {
     vertx.cancelTimer(timerID);
   }
 
+  public void timerExample(Vertx vertx) {
+    // Create a timer
+    Future<String> timer = vertx
+      .timer(10, TimeUnit.SECONDS)
+      .map(v -> "Success");
+
+    timer.onSuccess(value -> {
+      System.out.println("Timer fired: " + value);
+    });
+    timer.onFailure(cause -> {
+      System.out.println("Timer cancelled: " + cause.getMessage());
+    });
+  }
+
   public void example18(String className, Exception exception) {
 
     // Note -these classes are Java only