4 files changed, 105 insertions, 17 deletions
diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index acc1454..b9fbbc2 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -16,7 +16,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
-// @todo * link:man:gun:shutdown(3)[gun:shutdown(3)] - Gracefully close 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
 
@@ -144,6 +144,7 @@ Handshake timeout for tunneled TLS connections.
 [source,erlang]
 ----
 http_opts() :: #{
+    closing_timeout       => timeout(),
     flow                  => pos_integer(),
     keepalive             => timeout(),
     transform_header_name => fun((binary()) -> binary()),
@@ -157,6 +158,12 @@ The default value is given next to the option name:
 
 // @todo Document content_handlers and gun_sse_h.
 
+closing_timeout (15000)::
+
+Time to wait before brutally closing the connection when a
+graceful shutdown was requested via a call to
+link:man:gun:shutdown(3)[gun:shutdown(3)].
+
 flow - see below::
 
 The initial flow control value for all HTTP/1.1 streams.
@@ -188,8 +195,9 @@ HTTP version to use.
 [source,erlang]
 ----
 http2_opts() :: #{
-    flow      => pos_integer(),
-    keepalive => timeout()
+    closing_timeout => timeout(),
+    flow            => pos_integer(),
+    keepalive       => timeout()
 }
 ----
 
@@ -199,6 +207,12 @@ The default value is given next to the option name:
 
 // @todo Document content_handlers and gun_sse_h.
 
+closing_timeout (15000)::
+
+Time to wait before brutally closing the connection when a
+graceful shutdown was requested either via a call to
+link:man:gun:shutdown(3)[gun:shutdown(3)] or by the server.
+
 flow - see below::
 
 The initial flow control value for all HTTP/2 streams.
@@ -364,9 +378,10 @@ The pid of the process that will receive the response messages.
 [source,erlang]
 ----
 ws_opts() :: #{
-    compress  => boolean(),
-    flow      => pos_integer(),
-    protocols => [{binary(), module()}]
+    closing_timeout => timeout(),
+    compress        => boolean(),
+    flow            => pos_integer(),
+    protocols       => [{binary(), module()}]
 }
 ----
 
@@ -374,6 +389,12 @@ Configuration for the Websocket protocol.
 
 The default value is given next to the option name:
 
+closing_timeout (15000)::
+
+Time to wait before brutally closing the connection when a
+graceful shutdown was requested either via a call to
+link:man:gun:shutdown(3)[gun:shutdown(3)] or by the server.
+
 compress (false)::
 
 Whether to enable permessage-deflate compression. This does
diff --git a/doc/src/manual/gun.close.asciidoc b/doc/src/manual/gun.close.asciidoc
index 20fd1bf..cdbe05f 100644
--- a/doc/src/manual/gun.close.asciidoc
+++ b/doc/src/manual/gun.close.asciidoc
@@ -41,4 +41,5 @@ ok = gun:close(ConnPid).
 
 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:open_unix(3)[gun:open_unix(3)],
+link:man:gun:shutdown(3)[gun:shutdown(3)]
diff --git a/doc/src/manual/gun.shutdown.asciidoc b/doc/src/manual/gun.shutdown.asciidoc
new file mode 100644
index 0000000..94db39d
--- /dev/null
+++ b/doc/src/manual/gun.shutdown.asciidoc
@@ -0,0 +1,67 @@
+= gun:shutdown(3)
+
+== Name
+
+gun:shutdown - Gracefully close the connection
+
+== Description
+
+[source,erlang]
+----
+shutdown(ConnPid) -> ok
+
+ConnPid :: pid()
+----
+
+Gracefully close the connection.
+
+Gun will wait for up to `closing_timeout` milliseconds
+before brutally closing the connection. The graceful
+shutdown mechanism varies between the different protocols:
+
+* For HTTP/1.1 there is no such mechanism and Gun will
+  close the connection once the current response is
+  received. Any pipelined requests are immediately
+  terminated.
+
+* For HTTP/2 Gun will send a GOAWAY frame and wait for
+  the existing streams to terminate.
+
+* For Websocket Gun will send a close frame and wait
+  for the server's close frame before closing the
+  connection.
+
+The function returns immediately. The connection may
+therefore still be up for some time after this call.
+
+Gun will not attempt to reconnect once graceful
+shutdown has been initiated.
+
+== Arguments
+
+ConnPid::
+
+The pid of the Gun connection process.
+
+== Return value
+
+The atom `ok` is returned.
+
+== Changelog
+
+* *2.0*: Function introduced.
+
+== Examples
+
+.Gracefully shutdown the connection
+[source,erlang]
+----
+ok = gun:shutdown(ConnPid).
+----
+
+== 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:close(3)[gun:close(3)]
diff --git a/doc/src/manual/gun.ws_send.asciidoc b/doc/src/manual/gun.ws_send.asciidoc
index fbb1025..b39f3f0 100644
--- a/doc/src/manual/gun.ws_send.asciidoc
+++ b/doc/src/manual/gun.ws_send.asciidoc
@@ -30,8 +30,7 @@ The pid of the Gun connection process.
 
 Frames::
 
-A Websocket frame.
-// @todo One or more Websocket frame(s).
+One or more Websocket frame(s).
 
 == Return value
 
@@ -49,14 +48,14 @@ The atom `ok` is returned.
 gun:ws_send(ConnPid, {text, <<"Hello world!">>}).
 ----
 
-//.Send many frames including a close frame
-//[source,erlang]
-//----
-//gun:ws_send(ConnPid, [
-//    {text, <<"See you later, world!">>},
-//    close
-//]).
-//----
+.Send many frames including a close frame
+[source,erlang]
+----
+gun:ws_send(ConnPid, [
+    {text, <<"See you later, world!">>},
+    close
+]).
+----
 
 == See also