Resolved some comments

* Renamed pub/sub section to System events, removed paragraph about pub/sub, moved the event definition to Event watchers section
* Removed code-block with empty table for the event values
* Fixed some refs and links

Author: xuniq

doc/reference/reference_lua/box.rst

@@ -34,7 +34,6 @@ with ``box``, with no arguments. The ``box`` module contains:
     box_space
     box_stat
     box_tuple
-    box_watchers
 
     box_txn_management
     box_sql

doc/reference/reference_lua/box_events.rst

@@ -1,49 +1,53 @@
 .. _box-watchers:
 
---------------------------------------------------------------------------------
 Event watchers
---------------------------------------------------------------------------------
+==============
 
-The ``box`` module contains some functions related to event subscriptions, also known as watchers.
-The subscriptions are used to inform a client about server-side events.
-To read more about the built-in events in Tarantool,
-check the :doc:`pub/sub </reference/reference_lua/box_events/pub-sub>` section.
+The ``box`` module contains some features related to event subscriptions, also known as :term:`watchers <watcher>`.
+The subscriptions are used to inform a client about server-side :term:`events <event>`.
+Each event subscription is defined by a certain key.
 
 ..  glossary::
 
-    Watcher
-        A watcher is a :doc:`callback </book/box/triggers>` that is invoked when a state change occurs.
-        To register a local watcher, use the ``box.watch()`` function.
-        To create a remote watcher, user the ``conn:watch()`` function.
-        Note that it is possible to register more than one watcher for the same key.
+    Event
+
+        An event is a state change or a system update that triggers the action of other systems.
+        To read more about the built-in events in Tarantool,
+        check the :doc:`system events </reference/reference_lua/box_events/system_events>` section.
 
     State
         A state is an internally stored key-value pair.
         The key is a string.
         The value is an arbitrary type that can be encoded as MsgPack.
         To update a state, use the ``box.broadcast()`` function.
 
-First, a watcher callback is invoked after the watcher registration.
+    Watcher
+        A watcher is a :doc:`callback </book/box/triggers>` that is invoked when a state change occurs.
+        To register a local watcher, use the ``box.watch()`` function.
+        To create a remote watcher, use the ``watch()`` function from the ``net.box`` module.
+        Note that it is possible to register more than one watcher for the same key.
+
+How the watcher works
+---------------------
+
+First, you register a watcher.
+After that, the watcher callback is invoked for the first time.
 In this case, the callback is triggered whether or not the key has already been broadcast.
-After that, :doc:`box.broadcast() </reference/reference_lua/box_watchers/broadcast>`  called on the remote host
-triggers all subsequent invocations.
+All subsequent invocations are triggered with the :doc:`box.broadcast() </reference/reference_lua/box_events/broadcast>`
+called on the remote host.
 If a watcher is subscribed for a key that has not been broadcast yet, the callback is triggered only once,
 after the registration of the watcher.
 
-A watcher callback is passed the name of the key for which it was registered and the current key data.
-A watcher callback is always invoked in a new fiber. It means that is is okay to yield in it.
+The watcher callback takes two arguments.
+The first argument is a name of the key for which it was registered.
+The second one contains current key data.
+The callback is always invoked in a new fiber. It means that is is okay to yield in it.
 A watcher callback is never executed in parallel with itself.
 If the key is updated while the watcher callback is running, the callback will be invoked again with the new
 value as soon as it returns.
 
 ``box.watch`` and ``box.broadcast`` functions can be used before :doc:`box.cfg </reference/reference_lua/box_cfg>`.
 
-..  note::
-
-    Keep in mind that garbage collection of a watcher handle doesn't lead to the watcher's destruction.
-    In this case, the watcher remains registered.
-    It is okay to discard the result of ``watch`` function if the watcher will never be unregistered.
-
 Below is a list of all functions and members related to watchers or events.
 
 ..  container:: table
@@ -58,21 +62,21 @@ Below is a list of all functions and members related to watchers or events.
         *   - Name
             - Use
 
-        *  - :doc:`./box_watchers/watch`
+        *  - :doc:`./box_events/watch`
            - Create a local watcher.
 
         *  - :ref:`conn:watch() <conn-watch>`
            - Create a watcher for the remote host.
 
-        *  - :doc:`./box_watchers/broadcast`
+        *  - :doc:`./box_events/broadcast`
            - Update a state.
 
-        *  - :ref:`˜Built-in events <pubsub>`
-           - Pub/sub system and predefined events
+        *  - :ref:`˜Built-in events <system-events>`
+           - Predefined events in Tarantool
 
 .. toctree::
     :hidden:
 
     box_events/watch
     box_events/broadcast
-    box_events/pub-sub
+    box_events/system_events

doc/reference/reference_lua/box_events/pub-sub.rst renamed to doc/reference/reference_lua/box_events/system_events.rst

@@ -1,38 +1,7 @@
-.. _pubsub:
+.. _system-events:
 
-Pub/sub system and its events
-=============================
-
-Overview
---------
-
-In Tarantool, :term:`pub/sub <publisher/subscriber>` is a :term:`notification` system for server-side
-:term:`events <event>`.
-
-..  glossary::
-
-    event
-
-        An event is a state change or a system update update that triggers the action of other systems.
-
-    publisher/subscriber
-
-        A publish/subscribe pattern, also shortened as pub/sub, is a design pattern that consists of
-        event producers (publishers), event consumers (subscribers or watchers), and event channel.
-        Publishers communicate with watchers asynchronously by broadcasting events.
-        They sent events to the pub/sub system.
-        Then the system delivers received events to all the watchers that react to them.
-
-    notification
-
-        A notification is a message created by one side to inform about the occurrence of the event and describe
-        it to other components.
-
-The pub/sub pattern is associated with subscriptions.
-Each subscription is defined by the certain key.
-
-Built-in events for pub/sub
----------------------------
+System events
+=============
 
 Predefined events have a special naming schema -- theirs names always start with the reserved ``box.`` prefix.
 It means that you cannot create new events with it.
@@ -47,15 +16,8 @@ The system processes the following events:
 In response to each event, the server sends back certain ``IPROTO`` fields.
 
 The events are available from the beginning as non-:ref:`MP_NIL <box_protocol-notation>`.
-If the events are broadcast before :doc:`box.cfg{} </reference/reference_lua/box_cfg>`,
-then the events values are empty:
-
-..  code-block:: lua
-
-    box.id = {}
-    box.schema = {}
-    box.status = {}
-    box.election = {}
+If a watcher subscribes to a system event before it has been broadcast,
+it receives an empty table for the event value.
 
 box.id
 ~~~~~~

doc/reference/reference_lua/box_events/watch.rst

@@ -15,6 +15,12 @@ box.watch()
 
     To read more about watchers, see the `Functions for watchers <box-watchers>` section.
 
+    ..  note::
+
+        Keep in mind that garbage collection of a watcher handle doesn't lead to the watcher's destruction.
+        In this case, the watcher remains registered.
+        It is okay to discard the result of ``watch`` function if the watcher will never be unregistered.
+
     **Example:**
 
     ..  code-block:: lua

doc/reference/reference_lua/net_box.rst

@@ -547,7 +547,7 @@ Below is a list of all ``net.box`` functions.
 
         To read more about watchers, see the `Functions for watchers <box-watchers>` section.
 
-        The method has the same syntax as the :doc:`box.watch() </reference/reference_lua/box_watchers/broadcast>`
+        The method has the same syntax as the :doc:`box.watch() </reference/reference_lua/box_events/broadcast>`
         function, which is used for subscribing to events locally.
 
         Watchers survive reconnection (see the ``reconnect_after`` connection :ref:`option <net_box-new>`).
@@ -558,6 +558,12 @@ Below is a list of all ``net.box`` functions.
         connection ``peer_protocol_features``.
         For details, check the :ref:`net.box features table <net_box-new>`.
 
+        ..  note::
+
+            Keep in mind that garbage collection of a watcher handle doesn't lead to the watcher's destruction.
+            In this case, the watcher remains registered.
+            It is okay to discard the result of ``watch`` function if the watcher will never be unregistered.
+
         **Example:**
 
         Server:
@@ -575,7 +581,7 @@ Below is a list of all ``net.box`` functions.
             -- Subscribe to updates of the 'foo' key.
             w = conn:watch('foo', function(key, value)
                 assert(key == 'foo')
-            -- do something with value
+                -- do something with value
             end)
             -- Unregister the watcher if it is no longer needed.
             w:unregister()