Use maps for and improve options

The type option has been removed. The transport and protocols
options can be used in its place.

The transport_opts option can be used to specify transport
options.

The http_opts and spdy_opts options can be used to specify
protocol specific options.

The keepalive option is now a protocol specific option.

Defaults depending on the port number have changed. Now only
port 443 uses ssl by default, other ports use tcp.

2 files changed, 65 insertions, 25 deletions

diff --git a/doc/src/guide/connect.asciidoc b/doc/src/guide/connect.asciidoc
index e1ad56e..e2bcaa7 100644
--- a/doc/src/guide/connect.asciidoc
+++ b/doc/src/guide/connect.asciidoc
@@ -33,16 +33,24 @@ The `gun:open/{2,3}` function must be used to open a connection.
 [source,erlang]
 {ok, ConnPid} = gun:open("example.org", 443).
 
-@todo open/3
-@todo make opts a map
+If the port given is 443, Gun will attempt to connect using
+SSL. The protocol will be selected automatically using the
+NPN extension for TLS. By default Gun supports SPDY/3.1,
+SPDY/3 and HTTP/1.1 when connecting using SSL.
 
-If the port given is 80, Gun will attempt to connect using
-TCP and use the HTTP/1.1 protocol. For any other port, TLS
-will be used. The NPN extension for TLS allows Gun to select
-SPDY automatically if the server supports it. Otherwise,
-HTTP/1.1 will be used.
+For any other port, Gun will attempt to connect using TCP
+and will use the HTTP/1.1 protocol.
 
-@todo more about defaults
+The transport and protocol used can be overriden using
+options. The manual documents all available options.
+
+Options can be provided as a third argument, and take the
+form of a map.
+
+.Opening an SSL connection to example.org on port 8443
+
+[source,erlang]
+{ok, ConnPid} = gun:open("example.org", 8443, #{transport=>ssl}).
 
 === Monitoring the connection process
 
diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index 14641ee..9d592a8 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -12,30 +12,62 @@ HTTP or Websocket.
 
 == Types
 
-=== opts() = [opt()]
+=== opts() = map()
 
 Configuration for the connection.
 
-@todo Should be a map.
-
-With opt():
-
-keepalive => pos_integer()::
-	Time between pings in milliseconds.
-	Defaults to 5000.
+The following keys are defined:
+
+http_opts => gun:http_opts()::
+	Options specific to the HTTP protocol. See below.
+protocols => [http | spdy]::
+	Ordered list of preferred protocols. When the transport is tcp,
+	this list must contain exactly one protocol. When the transport
+	is ssl, this list must contain at least one protocol and will be
+	used using the NPN protocol negotiation method. When the server
+	does not support NPN then http will always be used. Defaults to
+	[http] when the transport is tcp, and [spdy, http] when the
+	transport is ssl.
 retry => non_neg_integer()::
 	Number of times Gun will try to reconnect on failure before giving up.
 	Defaults to 5.
 retry_timeout => pos_integer()::
-	Time between retries in milliseconds.
-	Defaults to 5000.
-type => ssl | tcp | tcp_spdy::
-	Whether to use SSL, plain TCP (for HTTP/Websocket) or SPDY over TCP.
-	The default varies depending on the port used. Port 443 defaults
-	to ssl. Port 6121 defaults to tcp_spdy (@todo). All other ports
-	default to tcp. (@todo)
-
-@todo We want to separate protocol and transport options.
+	Time between retries in milliseconds. Defaults to 5000.
+spdy_opts => gun:spdy_opts()::
+	Options specific to the SPDY protocol. See below.
+trace => boolean()::
+	Whether to enable `dbg` tracing of the connection process. Should
+	only be used during debugging. Defaults to false.
+transport => tcp | ssl::
+	Whether to use SSL or plain TCP. The default varies depending on the
+	port used. Port 443 defaults to ssl. All other ports default to tcp.
+transport_opts => proplists:proplist()::
+	Transport options. They are TCP options or SSL options depending on
+	the selected transport.
+
+=== http_opts() = map()
+
+Configuration for the HTTP protocol.
+
+The following keys are defined:
+
+keepalive => pos_integer()::
+	Time between pings in milliseconds. Since the HTTP protocol has
+	no standardized way to ping the server, Gun will simply send an
+	empty line when the connection is idle. Gun only makes a best
+	effort here as servers usually have configurable limits to drop
+	idle connections. Defaults to 5000.
+version => 'HTTP/1.1' | 'HTTP/1.0'::
+	HTTP version to use. Defaults to 'HTTP/1.1'.
+
+=== spdy_opts() = map()
+
+Configuration for the SPDY protocol.
+
+The following keys are defined:
+
+keepalive => pos_integer()::
+	Time between pings in milliseconds. Defaults to 5000.
 
 @todo We need to document Websocket options.