From 8670f651135cbf446173840c1a6ac8f3e024a257 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Mon, 4 Jun 2018 11:30:53 +0200
Subject: Review and update the user guide

---
 doc/src/guide/websocket.asciidoc | 97 ++++++++++++++++++++--------------------
 1 file changed, 49 insertions(+), 48 deletions(-)

(limited to 'doc/src/guide/websocket.asciidoc')

diff --git a/doc/src/guide/websocket.asciidoc b/doc/src/guide/websocket.asciidoc
index f99dea7..cf32291 100644
--- a/doc/src/guide/websocket.asciidoc
+++ b/doc/src/guide/websocket.asciidoc
@@ -1,10 +1,10 @@
+[[websocket]]
 == Websocket
 
 This chapter describes how to use the Gun client for
 communicating with a Websocket server.
 
-@todo recovering from connection failure
-reconnecting to Websocket etc.
+// @todo recovering from connection failure, reconnecting to Websocket etc.
 
 === HTTP upgrade
 
@@ -14,33 +14,33 @@ HTTP/1.1 connections can be upgraded to Websocket, so you might
 need to restrict the protocol to HTTP/1.1 if you are planning
 to use Websocket over TLS.
 
-You must use the `gun_ws:upgrade/{2,3,4}` function to upgrade
+You must use the `gun:ws_upgrade/2,3,4` function to upgrade
 to Websocket. This function can be called anytime after connection,
 so you can send HTTP requests before upgrading to Websocket.
 
 .Upgrade to Websocket
-
 [source,erlang]
+----
 gun:ws_upgrade(ConnPid, "/websocket").
+----
 
 Gun will set all the necessary headers for performing the
 Websocket upgrade, but you can specify additional headers
 if needed. For example you can request a custom sub-protocol.
 
 .Upgrade to Websocket and request a protocol
-
 [source,erlang]
+----
 gun:ws_upgrade(ConnPid, "/websocket", [
-	{<<"sec-websocket-protocol">>, "mychat"}
+    {<<"sec-websocket-protocol">>, "mychat"}
 ]).
+----
 
-You can pass the Websocket options as part of the `gun:open/{2,3}`
+You can pass the Websocket options as part of the `gun:open/2,3`
 call when opening the connection, or using the `gun:ws_upgrade/4`.
-The fourth argument is those same options. This function call
-will crash if the options are incorrect, unlike when passing
-them through `gun:open/{2,3}`.
+The fourth argument is those same options.
 
-When the upgrade succeeds, a `gun_ws_upgrade` message is sent.
+When the upgrade succeeds, a `gun_upgrade` message is sent.
 If the server does not understand Websocket or refused the
 upgrade, a `gun_response` message is sent. If Gun couldn't
 perform the upgrade due to an error (for example attempting
@@ -52,21 +52,19 @@ a meaningful response which should be processed. In the
 following example we however ignore it:
 
 [source,erlang]
+----
 receive
-	{gun_ws_upgrade, ConnPid, ok, Headers} ->
-		upgrade_success(ConnPid);
-	{gun_response, ConnPid, _, _, Status, Headers} ->
-		exit({ws_upgrade_failed, Status, Headers});
-	{gun_error, ConnPid, StreamRef, Reason} ->
-		exit({ws_upgrade_failed, Reason})
-	%% More clauses here as needed.
+    {gun_upgrade, ConnPid, StreamRef, [<<"websocket">>], Headers} ->
+        upgrade_success(ConnPid, StreamRef);
+    {gun_response, ConnPid, _, _, Status, Headers} ->
+        exit({ws_upgrade_failed, Status, Headers});
+    {gun_error, ConnPid, StreamRef, Reason} ->
+        exit({ws_upgrade_failed, Reason})
+    %% More clauses here as needed.
 after 1000 ->
-	exit(timeout)
+    exit(timeout)
 end.
-
-Note that you shouldn't use the `reply_to` request option
-for connections you plan to upgrade, because only the
-owner of the connection will receive messages about it.
+----
 
 === Sending data
 
@@ -74,27 +72,28 @@ Once the Websocket upgrade has completed successfully, you no
 longer have access to functions for performing requests. You
 can only send and receive Websocket messages.
 
-Use `gun:ws_send/2` to send one or more messages to the server.
-
-@todo Implement sending of N frames
+Use `gun:ws_send/2` to send messages to the server.
 
 .Send a text frame
-
 [source,erlang]
+----
 gun:ws_send(ConnPid, {text, "Hello!"}).
-
-.Send a text frame, a binary frame and then close the connection
-
-[source,erlang]
-gun:ws_send(ConnPid, [
-	{text, "Hello!"},
-	{binary, BinaryValue},
-	close
-]).
+----
+
+// @todo Implement sending of N frames
+//
+//.Send a text frame, a binary frame and then close the connection
+//[source,erlang]
+//----
+//gun:ws_send(ConnPid, [
+//    {text, "Hello!"},
+//    {binary, BinaryValue},
+//    close
+//]).
+//----
 
 Note that if you send a close frame, Gun will close the connection
-cleanly and will not attempt to reconnect afterwards, similar to
-calling `gun:shutdown/1`.
+cleanly and will not attempt to reconnect afterwards.
 
 === Receiving data
 
@@ -102,15 +101,17 @@ Gun sends an Erlang message to the owner process for every
 Websocket message it receives.
 
 [source,erlang]
+----
 receive
-	{gun_ws, ConnPid, Frame} ->
-		handle_frame(ConnPid, Frame)
+    {gun_ws, ConnPid, StreamRef, Frame} ->
+        handle_frame(ConnPid, StreamRef, Frame)
 end.
-
-@todo auto ping has not been implemented yet
-
-Gun will automatically send ping messages to the server to keep
-the connection alive, however if the connection dies and Gun has
-to reconnect it will not upgrade to Websocket automatically, you
-need to perform the operation when you receive the `gun_error`
-message.
+----
+
+// @todo auto ping has not been implemented yet
+//
+//Gun will automatically send ping messages to the server to keep
+//the connection alive, however if the connection dies and Gun has
+//to reconnect it will not upgrade to Websocket automatically, you
+//need to perform the operation when you receive the `gun_error`
+//message.
-- 
cgit v1.2.3

