Add docs for notify_settings_changed in http2_opts()

LH: I have expanded and documented gun_notify in its own page.

3 files changed, 66 insertions, 0 deletions

diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index ece9d2a..212cc60 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -66,6 +66,7 @@ Connection:
 * link:man:gun_up(3)[gun_up(3)] - The connection is up
 * link:man:gun_tunnel_up(3)[gun_tunnel_up(3)] - The tunnel is up
 * link:man:gun_down(3)[gun_down(3)] - The connection is down
+* link:man:gun_notify(3)[gun_notify(3)] - Optional event notification
 * link:man:gun_upgrade(3)[gun_upgrade(3)] - Successful protocol upgrade
 * link:man:gun_error(3)[gun_error(3)] - Stream or connection-wide error
 
@@ -210,6 +211,7 @@ http2_opts() :: #{
     flow                        => pos_integer(),
     keepalive                   => timeout(),
     keepalive_tolerance         => non_neg_integer(),
+    notify_settings_changed     => boolean(),
 
     %% HTTP/2 state machine configuration.
     connection_window_margin_size  => 0..16#7fffffff,
@@ -266,6 +268,11 @@ tolerated before the connection is closed. By default
 this mechanism is disabled even if `keepalive` is
 enabled.
 
+notify_settings_changed (false)::
+
+Whether Gun should send a link:man:gun_notify(3)[gun_notify(3)] message
+to the user when settings are changed by the server.
+
 === opts()
 
 [source,erlang]
@@ -600,6 +607,8 @@ By default no user option is defined.
 
 == Changelog
 
+* *2.2*: The `notify_settings_changed` option for HTTP/2 was
+         documented.
 * *2.2*: The `reply_to` option now accepts functions.
 * *2.1*: The HTTP/2 option list was updated with new options.
 * *2.0*: The `default_protocol` and `user_opts` Websocket
diff --git a/doc/src/manual/gun.info.asciidoc b/doc/src/manual/gun.info.asciidoc
index db0916d..fe81e0e 100644
--- a/doc/src/manual/gun.info.asciidoc
+++ b/doc/src/manual/gun.info.asciidoc
@@ -49,6 +49,7 @@ the connection.
 
 == Changelog
 
+* *2.2*: The value `state_name` was added.
 * *2.0*: The values `owner`, `origin_scheme` and `cookie_store` were
          added.
 * *1.3*: The values `socket`, `transport`, `protocol`, `origin_host`,
diff --git a/doc/src/manual/gun_notify.asciidoc b/doc/src/manual/gun_notify.asciidoc
new file mode 100644
index 0000000..5f268ab
--- /dev/null
+++ b/doc/src/manual/gun_notify.asciidoc
@@ -0,0 +1,56 @@
+= gun_notify(3)
+
+== Name
+
+gun_notify - Optional event notification
+
+== Description
+
+[source,erlang]
+----
+{gun_notify, ConnPid, settings_changed, Settings}
+
+ConnPid  :: pid()
+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.
+
+== Elements
+
+ConnPid::
+
+The pid of the Gun connection process.
+
+Event::
+
+Identifier for the event. Currently can only be
+`settings_changed`.
+
+Data::
+
+Data for the event. Currently can only be the
+new connection settings.
+
+== Changelog
+
+* *2.2*: Message introduced.
+
+== Examples
+
+.Receive a gun_notify message in a gen_server
+[source,erlang]
+----
+handle_info({gun_notify, ConnPid, settings_changed, Settings},
+            State=#state{conn_pid=ConnPid}) ->
+    %% Do something.
+    {noreply, State}.
+----
+
+== See also
+
+link:man:gun(3)[gun(3)]