diff --git a/src/main/asciidoc/http.adoc b/src/main/asciidoc/http.adoc
index 079de39f9..95ecece9a 100644
--- a/src/main/asciidoc/http.adoc
+++ b/src/main/asciidoc/http.adoc
@@ -1369,7 +1369,7 @@ The {@link io.vertx.core.http.HttpClientRequest#connection()} method returns the
 {@link examples.HTTP2Examples#example18}
 ----
 
-A connection handler can be set on the request to be notified when the connection happens:
+A connection handler can be set on the client to be notified when a connection has been established happens:
 
 [source,$lang]
 ----
diff --git a/src/main/java/examples/HTTP2Examples.java b/src/main/java/examples/HTTP2Examples.java
index 9620ff5c1..19fa68afb 100644
--- a/src/main/java/examples/HTTP2Examples.java
+++ b/src/main/java/examples/HTTP2Examples.java
@@ -214,8 +214,8 @@ public class HTTP2Examples {
     HttpConnection connection = request.connection();
   }
 
-  public void example19(HttpClientRequest request) {
-    request.connectionHandler(connection -> {
+  public void example19(HttpClient client) {
+    client.connectionHandler(connection -> {
       System.out.println("Connected to the server");
     });
   }
diff --git a/src/main/java/io/vertx/core/http/HttpClientRequest.java b/src/main/java/io/vertx/core/http/HttpClientRequest.java
index a930681ab..4cb28ff54 100644
--- a/src/main/java/io/vertx/core/http/HttpClientRequest.java
+++ b/src/main/java/io/vertx/core/http/HttpClientRequest.java
@@ -427,7 +427,9 @@ public interface HttpClientRequest extends WriteStream<Buffer>, ReadStream<HttpC
    *
    * @param handler the handler
    * @return a reference to this, so the API can be used fluently
+   * @deprecated instead use {@link HttpClient#connectionHandler(Handler)}
    */
+  @Deprecated
   @Fluent
   HttpClientRequest connectionHandler(@Nullable Handler<HttpConnection> handler);