Document Socks support

Also correct various Socks related types. This commit also
adds a new gun:protocols/0 type as a simpler way of describing
preferred protocols. The protocol/opts tuple is also documented.

This commit also fixes an issue with the default value for the
preferred protocols when using CONNECT over TLS. It was
mistakenly not enabling http2 by default.

1 files changed, 66 insertions, 0 deletions

diff --git a/doc/src/manual/gun_socks_up.asciidoc b/doc/src/manual/gun_socks_up.asciidoc
new file mode 100644
index 0000000..e74f1a9
--- /dev/null
+++ b/doc/src/manual/gun_socks_up.asciidoc
@@ -0,0 +1,66 @@
+= gun_socks_up(3)
+
+== Name
+
+gun_socks_up - The Socks connection is up
+
+== Description
+
+[source,erlang]
+----
+{gun_socks_up, ConnPid, Protocol}
+
+ConnPid  :: pid()
+Protocol :: http | http2 | socks
+----
+
+The Socks connection is up.
+
+This message informs the owner process that the connection
+completed through the configured Socks proxy.
+
+If Gun is configured to connect to another Socks server, then the
+connection is not usable yet. One or more
+link:man:gun_socks_up(3)[gun_socks_up(3)] messages will follow.
+
+Otherwise, Gun will start processing the messages it received while
+waiting for the connection to be up. If this is a reconnection,
+then this may not be desirable for all requests. Those requests
+should be cancelled when the connection goes down, and any
+subsequent messages ignored.
+
+== Elements
+
+ConnPid::
+
+The pid of the Gun connection process.
+
+Protocol::
+
+The protocol selected for this connection. It can be used
+to determine the capabilities of the server.
+
+== Changelog
+
+* *2.0*: Message introduced.
+
+== Examples
+
+.Receive a gun_socks_up message in a gen_server
+[source,erlang]
+----
+handle_info({gun_socks_up, ConnPid, _Protocol},
+            State=#state{conn_pid=ConnPid}) ->
+    %% Do something.
+    {noreply, State}.
+----
+
+== See also
+
+link:man:gun(3)[gun(3)],
+link:man:gun:open(3)[gun:open(3)],
+link:man:gun:open_unix(3)[gun:open_unix(3)],
+link:man:gun:await_up(3)[gun:await_up(3)],
+link:man:gun_up(3)[gun_up(3)],
+link:man:gun_down(3)[gun_down(3)],
+link:man:gun_error(3)[gun_error(3)]