Apply suggestions from code review

Author: xuniq

doc/dev_guide/internals/box_protocol.rst

@@ -1082,9 +1082,20 @@ Graceful shutdown protocol
 
 Since :doc:`2.10.0 </release/2.10.0>`.
 
+The graceful shutdown protocol is a mechanism that helps to prevent data loss in requests in case of a shutdown command.
+According to the protocol, when a server receives an ``os.exit()`` command or a ``SIGTERM``  signal,
+it does not exit immediately.
+Instead of that, first, the server stops listening for new connections.
+Then, the server sends the shutdown packets to all connections that support the graceful shutdown protocol.
+When a client is notified about the upcoming server exit, it stops serving any new requests and
+waits for active requests to complete before closing the connections.
+Once all connections are terminated, the server will be shut down.
+
 The protocol uses the event subscription system.
-For more information about it, see :ref:`box.shutdown <system-events_box-shutdown>`
-and :ref:`reference for the event watchers <box-watchers>`.
+That is, the feature is available if a server supports :ref:`box.shutdown <system-events_box-shutdown>` event
+and ``IPROTO_WATCH``.
+For more information about it, see :ref:`reference for the event watchers <box-watchers>`
+and the :ref:`corresponding section <box-protocol-watchers>` in Box Protocol.
 
 The shutdown protocol works in the following way:
 
@@ -1095,7 +1106,7 @@ The shutdown protocol works in the following way:
     The server broadcasts it to all subscribed remote watchers (see :ref:`IPROTO_WATCH <box_protocol-watch>`).
     That is, the server calls :ref:`box.broadcast('box.shutdown', true) <box-broadcast>`
     from the :ref:`box.ctl.on_shutdown() <box_ctl-on_shutdown>` trigger callback.
-    Once this is done, the server stops accepting new connections.
+    Once this is done, the server stops listening for new connections.
 
 #.  From now on, the server waits until all subscribed connections are terminated.
 

doc/reference/reference_lua/box_ctl/set_on_shutdown_timeout.rst

@@ -10,7 +10,7 @@ box.ctl.set_on_shutdown_timeout()
 
      Set a timeout for the :ref:`on_shutdown <box_ctl-on_shutdown>` trigger.
      If the timeout has expired, the server stops immediately
-     regardless of whether there are any ``on_shutdown`` triggers left.
+     regardless of whether any ``on_shutdown`` triggers are left unexecuted.
 
      :param double timeout: time to wait for the trigger to be completed. The default value is 3 seconds.
 

doc/reference/reference_lua/box_events/system_events.rst

@@ -29,7 +29,7 @@ This triggers the ``box.info`` event, which states that the value of ``box.info.
 while ``box.info.uuid`` and ``box.info.cluster.uuid`` remain the same.
 
 box.id
-~~~~~~
+------
 
 Contains :ref:`identification <box_info_info>` of the instance.
 Value changes are rare.
@@ -53,7 +53,7 @@ Value changes are rare.
     }
 
 box.status
-~~~~~~~~~~
+----------
 
 Contains generic information about the instance status.
 
@@ -70,7 +70,7 @@ Contains generic information about the instance status.
     }
 
 box.election
-~~~~~~~~~~~~
+------------
 
 Contains fields of :doc:`box.info.election </reference/reference_lua/box_info/election>`
 that are necessary to find out the most recent writable leader.
@@ -90,7 +90,7 @@ that are necessary to find out the most recent writable leader.
     }
 
 box.schema
-~~~~~~~~~~
+----------
 
 Contains schema-related data.
 
@@ -105,14 +105,17 @@ Contains schema-related data.
 .. _system-events_box-shutdown:
 
 box.shutdown
-~~~~~~~~~~~~
+------------
 
 Contains a boolean value which indicates whether there is an active shutdown request.
 
 The event is generated when the server receives a shutdown request (``os.exit()`` command or
 :ref:`SIGTERM <admin-server_signals>` signal).
 
-The ``box.shutdown`` event is supposed to be used with connectors.
+The ``box.shutdown`` event is applied for the graceful shutdown protocol.
+It is a feature which is available since :doc:`2.10.0 </release/2.10.0>`.
+This protocol is supposed to be used with connectors to signal a client about the upcoming server shutdown and
+close active connections without broken requests.
 For more information, refer to the :ref:`graceful shutdown protocol <box-protocol-shutdown>` section.
 
 Usage example

doc/reference/reference_lua/net_box.rst

@@ -56,6 +56,8 @@ Most ``net.box`` methods accept the last ``{options}`` argument, which can be:
   The default value is ``false``.
   For an example, see option description :ref:`below <net_box-return_raw>`.
 
+.. _net_box-state_diagram:
+
 The diagram below shows possible connection states and transitions:
 
 .. ifconfig:: builder not in ('latex', )
@@ -836,10 +838,10 @@ With the ``net.box`` module, you can use the following
 
     The trigger starts in a new fiber.
     While the ``on_shutdown()`` trigger is running, the connection stays active.
-    It means that it is allowed to send new requests from a trigger callback.
+    It means that the trigger callback is allowed to send new requests.
 
     After the trigger return, the ``net.box`` connection goes to the ``graceful_shutdown`` state
-    (check :ref:`the state diagram <net_box-options>` for details).
+    (check :ref:`the state diagram <net_box-state_diagram>` for details).
     In this state, no new requests are allowed.
     The connection waits for all pending requests to be completed.