Improve the gun:ping manual

3 files changed, 40 insertions, 24 deletions

diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index 212cc60..163040e 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -17,6 +17,7 @@ Connection:
 * link:man:gun:open(3)[gun:open(3)] - Open a connection to the given host and port
 * link:man:gun:open_unix(3)[gun:open_unix(3)] - Open a connection to the given Unix domain socket
 * link:man:gun:set_owner(3)[gun:set_owner(3)] - Set a new owner for the connection
+* link:man:gun:ping(3)[gun:ping(3)] - Check the health or RTT of the connection
 * link:man:gun:shutdown(3)[gun:shutdown(3)] - Gracefully close the connection
 * link:man:gun:close(3)[gun:close(3)] - Brutally close the connection
 * link:man:gun:info(3)[gun:info(3)] - Obtain information about the connection
@@ -450,7 +451,8 @@ Request headers.
 req_opts() :: #{
     flow     => pos_integer(),
     reply_to => pid() | {module(), atom(), list()}
-                      | fun((_) -> _) | {fun(), list()}
+                      | fun((_) -> _) | {fun(), list()},
+    tunnel   => gun:stream_ref()
 }
 ----
 
diff --git a/doc/src/manual/gun.ping.asciidoc b/doc/src/manual/gun.ping.asciidoc
index 96fd8b8..b312e9f 100644
--- a/doc/src/manual/gun.ping.asciidoc
+++ b/doc/src/manual/gun.ping.asciidoc
@@ -2,8 +2,7 @@
 
 == Name
 
-gun:ping - Check the health or the round-trip time of a connection
-without sending a request.
+gun:ping - Check the health or RTT of the connection
 
 == Description
 
@@ -17,20 +16,32 @@ ping(ConnPid, ReqOpts)
 
 ConnPid   :: pid()
 ReqOpts   :: gun:req_opts()
-PingRef   :: gun:stream_ref()
+PingRef   :: reference()
 ----
 
-Send a ping.
+Check the health or round-trip time of the connection.
 
-A ping can be sent to check the health or to measure the
-round-trip time of a connection, without sending a request.
+On protocols that support it, Gun will send a PING
+frame and wait for its corresponding acknowledgement.
+When it receives that acknowledgement the user process
+gets notified via a `gun_notify` message.
 
-The function `ping/1,2` sends a ping immediately, if the
-protocol supports pings. The server responds with a ping ack.
-A call to `gun:await/2,3` returns `ping_ack` when the ping
-ack has been received from the server.
+As this happens asynchronously and multiple pings
+can be sent concurrently, Gun returns a unique
+reference to the caller that can be used to identify
+the related acknowledgement.
 
-Currently, explicit ping is supported only for HTTP/2.
+The following protocols implement PING mechanisms
+and are supported by this function: HTTP/2.
+
+The following protocols implement PING mechanisms
+but are not yet supported by this function: HTTP/3
+and Websocket. Note that in the case of Websocket,
+the user can set `silence_pings` to `false` and
+send and receive PING frames.
+
+The following protocols do not implement PING
+mechanisms: HTTP/1.1, raw and SOCKS5.
 
 == Arguments
 
@@ -41,7 +52,7 @@ The pid of the Gun connection process.
 ReqOpts::
 
 Request options. Only the `reply_to` and `tunnel` options
-can be used.
+are relevant.
 
 == Return value
 
@@ -55,17 +66,15 @@ a ping ack is received from the server.
 
 == Examples
 
-.Perform a request
+.Send a ping and receive an ack
 [source,erlang]
 ----
 PingRef = gun:ping(ConnPid).
-receive
-    {gun_notify, ConnPid, ping_ack, PingRef} ->
-        ok
-end.
+{notify, ping_ack, PingRef} = gun:await(ConnPid, undefined).
 ----
 
 == See also
 
 link:man:gun(3)[gun(3)],
 link:man:gun:await(3)[gun:await(3)],
+link:man:gun_notify(3)[gun_notify(3)]
diff --git a/doc/src/manual/gun_notify.asciidoc b/doc/src/manual/gun_notify.asciidoc
index 5f268ab..90daee8 100644
--- a/doc/src/manual/gun_notify.asciidoc
+++ b/doc/src/manual/gun_notify.asciidoc
@@ -16,9 +16,13 @@ Settings :: map()
 
 Optional event notification.
 
-Only one event notification currently exists, for HTTP/2.
-This message informs the relevant process that the server
-has modified the connection settings.
+Only two event notifications currently exist:
+
+* `settings_changed` informs the user that the server has
+  modified its connection settings.
+
+* `ping_ack` informs the user that acknowledgement for a
+  user ping was received.
 
 == Elements
 
@@ -29,12 +33,12 @@ The pid of the Gun connection process.
 Event::
 
 Identifier for the event. Currently can only be
-`settings_changed`.
+`settings_changed` or `ping_ack`.
 
 Data::
 
 Data for the event. Currently can only be the
-new connection settings.
+new connection settings, or the ping reference.
 
 == Changelog
 
@@ -53,4 +57,5 @@ handle_info({gun_notify, ConnPid, settings_changed, Settings},
 
 == See also
 
-link:man:gun(3)[gun(3)]
+link:man:gun(3)[gun(3)],
+link:man:gun:ping(3)[gun:ping(3)]