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,10 +34,10 @@ with ``box``, with no arguments. The ``box`` module contains:
     box_space
     box_stat
     box_tuple
-    box_watchers
 
     box_txn_management
     box_sql
+    box_events
     box_once
     box_snapshot
 

doc/reference/reference_lua/box_events.rst

@@ -0,0 +1,82 @@
+.. _box-watchers:
+
+Event watchers
+==============
+
+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::
+
+    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.
+
+    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.
+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.
+
+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>`.
+
+Below is a list of all functions and members related to watchers or events.
+
+..  container:: table
+
+    ..  rst-class:: left-align-column-1
+    ..  rst-class:: left-align-column-2
+
+    ..  list-table::
+        :widths: 25 75
+        :header-rows: 1
+
+        *   - Name
+            - Use
+
+        *  - :doc:`./box_events/watch`
+           - Create a local watcher.
+
+        *  - :ref:`conn:watch() <conn-watch>`
+           - Create a watcher for the remote host.
+
+        *  - :doc:`./box_events/broadcast`
+           - Update a state.
+
+        *  - :ref:`˜Built-in events <system-events>`
+           - Predefined events in Tarantool
+
+.. toctree::
+    :hidden:
+
+    box_events/watch
+    box_events/broadcast
+    box_events/system_events

doc/reference/reference_lua/box_watchers/broadcast.rst renamed to doc/reference/reference_lua/box_events/broadcast.rst

@@ -0,0 +1,126 @@
+.. _system-events:
+
+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.
+
+The system processes the following events:
+
+*   ``box.id``
+*   ``box.status``
+*   ``box.election``
+*   ``box.schema``
+
+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 a watcher subscribes to a system event before it has been broadcast,
+it receives an empty table for the event value.
+
+box.id
+~~~~~~
+
+Contains :ref:`identification <box_info_info>` of the instance.
+Value changes are rare.
+
+*   ``id``: the numeric instance ID is unknown before the registration.
+    For anonymous replicas, the value is ``0`` until they are officially registered.
+
+*   ``instance_uuid``: the UUID of the instance never changes after the first
+    :doc:`box.cfg </reference/reference_lua/box_cfg>`.
+    The value is unknown before the ``box.cfg`` call.
+
+*   ``replicaset_uuid``: the value is unknown until the instance joins a replicaset or boots a new one.
+    The events start working before that -- right with the start of the listen.
+
+..  code-block:: lua
+
+    -- box.id value
+    {
+    MP_STR “id”: MP_UINT; box.info.id,
+    MP_STR “instance_uuid”: MP_UUID; box.info.uuid,
+    MP_STR “replicaset_uuid”: MP_UUID box.info.cluster.uuid,
+    }
+
+box.status
+~~~~~~~~~~
+
+Contains generic blob about the instance status.
+
+*   ``is_ro``: :ref:`indicates the read-only mode <box_introspection-box_info>` or the ``orphan`` status.
+*   ``is_ro_cfg``: indicates the :ref:`read_only <cfg_basic-read_only>` mode for the instance.
+*   ``status``: shows the status of an instance.
+
+..  code-block:: lua
+
+    {
+    MP_STR “is_ro”: MP_BOOL box.info.ro,
+    MP_STR “is_ro_cfg”: MP_BOOL box.cfg.read_only,
+    MP_STR “status”: MP_STR box.info.status,
+    }
+
+box.election
+~~~~~~~~~~~~
+
+Contains fields of the :doc:`box.info.election </reference/reference_lua/box_info/election>`
+that are necessary to find out the most recent writable leader.
+
+*   ``term``: shows the current election term.
+*   ``role``: indicates the election state of the node -- ``leader``, ``follower``, or ``candidate``.
+*   ``is_ro``: :ref:`indicates the read-only mode <box_introspection-box_info>` or the ``orphan`` status.
+*   ``leader``: shows the leader node ID in the current term.
+
+..  code-block:: lua
+
+    {
+    MP_STR “term”: MP_UINT box.info.election.term,
+    MP_STR “role”: MP_STR box.info.election.state,
+    MP_STR “is_ro”: MP_BOOL box.info.ro,
+    MP_STR “leader”: MP_UINT box.info.election.leader,
+    }
+
+box.schema
+~~~~~~~~~~
+
+Contains schema-related data.
+
+*   ``version``: shows the schema version.
+
+..  code-block:: lua
+
+    {
+    MP_STR “version”: MP_UINT schema_version,
+    }
+
+Usage example
+-------------
+
+..  code-block:: lua
+
+    conn = net.box.connect(URI)
+    -- Subscribe to updates of key 'box.id'
+    w = conn:watch('box.id', function(key, value)
+        assert(key == 'box.id')
+        -- do something with value
+    end)
+    -- or to updates of key 'box.status'
+    w = conn:watch('box.status', function(key, value)
+        assert(key == 'box.status')
+        -- do something with value
+    end)
+    -- or to updates of key 'box.election'
+    w = conn:watch('box.election', function(key, value)
+        assert(key == 'box.election')
+        -- do something with value
+    end)
+    -- or to updates of key 'box.schema'
+    w = conn:watch('box.schema', function(key, value)
+        assert(key == 'box.schema')
+        -- do something with value
+    end)
+    -- Unregister the watcher when it's no longer needed.
+    w:unregister()
+
+

doc/reference/reference_lua/box_events/system_events.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/box_watchers/watch.rst renamed to doc/reference/reference_lua/box_events/watch.rst

@@ -56,7 +56,6 @@ This reference covers Tarantool's built-in Lua modules.
     uri
     xlog
     yaml
-    pub-sub
     other
     errcodes
     debug_facilities

doc/reference/reference_lua/box_watchers.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()