Apply suggestions from the review

Author: xuniq

doc/dev_guide/internals/box_protocol.rst

@@ -25,7 +25,8 @@ The binary protocol provides complete access to Tarantool functionality, includi
     Since version :doc:`2.11.0 </release/2.11.0>`, you can use the :ref:`box.iproto <box_iproto>` submodule to access
     IPROTO constants and features from Lua. The submodule enables to :ref:`send arbitrary IPROTO packets <reference_lua-box_iproto_send>`
     over the session's socket and :ref:`override the behavior <reference_lua-box_iproto_override>` for all IPROTO
-    request types (including the :ref:`unknown <box_iproto-unknown>` types).
+    request types. Also, :ref:`IPROTO_UNKNOWN <box_iproto-unknown>` constant is introduced. The constant is used for the
+    :ref:`box.iproto.override() <reference_lua-box_iproto_override>` API, which allows setting a handler for incoming requests with an unknown type.
 
 ..  toctree::
     :maxdepth: 1

doc/dev_guide/internals/iproto/requests.rst

@@ -38,9 +38,9 @@ Overview
             -   0x8XXX |br| MP_INT
             -   Error response
 
-        *   -   :ref:`IPROTO_UNKNOWN <internals-iproto-keys-unknown>`
+        *   -   :ref:`IPROTO_UNKNOWN <internals-iproto-unknown>`
             -   -1 |br| MP_UINT
-            -   Unknown request type. The constant is used only for IPROTO handler :ref:`overriding <reference_lua-box_iproto_override>`.
+            -   Unknown request type
 
         *   -   :ref:`IPROTO_SELECT <box_protocol-select>`
             -   0x01
@@ -139,7 +139,7 @@ Since :doc:`2.11.0 </release/2.11.0>`.
 
 Code: -1.
 
-Unknown request type. The constant is used for overriding an unknown IPROTO request handler.
+Unknown request type. The constant is used to override the handler of unknown IPROTO request types.
 Learn more: :ref:`box.iproto.override() <reference_lua-box_iproto_override>` and :ref:`box_box_iproto_override <box_iproto_override>`.
 
 ..  _box_protocol-select:

doc/dev_guide/reference_capi/box.rst

@@ -324,7 +324,7 @@
     :param uint32_t request_type: IPROTO request type code (for example, ``IPROTO_SELECT``).
                                   For details, check :ref:`Client-server requests and responses <internals-requests_responses>`.
 
-                                  To override the handler of an unknown request type, use the :ref:`IPROTO_UNKNOWN <internals-iproto-keys-unknown>` type code.
+                                  To override the handler of unknown request types, use the :ref:`IPROTO_UNKNOWN <internals-iproto-keys-unknown>` type code.
 
     :param iproto_handler_t handler: IPROTO request handler. To reset the request handler, set the ``handler`` parameter to ``NULL``.
                                      See the full parameter description in the :ref:`Handler function <box_box_iproto_override-handler>` section.
@@ -343,11 +343,11 @@
 
     **Possible errors:**
 
-    If the Lua handler throws an exception, the behavior is similar to a remote procedure call.
+    If a Lua handler throws an exception, the behavior is similar to that of a remote procedure call.
     The following errors are returned to the client over IPROTO (see `src/lua/utils.h <https://github.com/tarantool/tarantool/blob/dec0e0221e183fa972efa65bb0fb658112f2196f/src/lua/utils.h#L366-L371>`__):
 
-    *   :errcode:`ER_PROC_LUA` -- the exception is thrown, diagnostic is not set.
-    *   diagnostics from ``src/box/errcode.h`` -- the exception is thrown, diagnostic is set.
+    *   :errcode:`ER_PROC_LUA` -- an exception is thrown from a Lua handler, diagnostic is not set.
+    *   diagnostics from ``src/box/errcode.h`` -- an exception is thrown, diagnostic is set.
 
     For details, see `src/box/errcode.h <https://github.com/tarantool/tarantool/blob/master/src/box/errcode.h>`__.
 
@@ -378,14 +378,17 @@
 
     The handler returns a status code. Possible statuses:
 
-    *  ``IPROTO_REQUEST_HANDLER_OK`` -- success
-    *  ``IPROTO_REQUEST_HANDLER_ERROR`` -- error, diagnostic must be set by handler
-    *  ``IPROTO_REQUEST_HANDLER_FALLBACK`` -- fallback to the system handler
+    *   ``IPROTO_REQUEST_HANDLER_OK`` -- success
+    *   ``IPROTO_REQUEST_HANDLER_ERROR`` -- error, diagnostic must be set by handler
+        (see :ref:`box_error_set() <c_api-error-box_error_set>` and :ref:`box_error_raise() <c_api-error-box_error_raise>`)
+
+    *   ``IPROTO_REQUEST_HANDLER_FALLBACK`` -- fallback to the default handler
 
 ..  _box_box_iproto_override-destroy:
 
     **Handler destructor function**
 
+    The destructor is called when the handler is reset.
     The signature of a destructor function (the ``destroy`` parameter):
 
     ..  code-block:: c

doc/dev_guide/reference_capi/error.rst

@@ -64,6 +64,8 @@
 
     Clear the last error.
 
+.. _c_api-error-box_error_set:
+
 .. c:function:: int box_error_set(const char *file, unsigned line, uint32_t code, const char *format, ...)
 
     Set the last error.
@@ -76,6 +78,8 @@
 
     See also: IPROTO :ref:`error code<capi-box_error_code>`
 
+.. _c_api-error-box_error_raise:
+
 .. c:macro:: box_error_raise(code, format, ...)
 
     A backward-compatible API define.

doc/reference/reference_lua/box_iproto.rst

@@ -6,12 +6,12 @@ Submodule box.iproto
 Since :doc:`2.11.0 </release/2.11.0>`.
 
 The ``box.iproto`` submodule provides the ability to work with the network subsystem of Tarantool.
-It enables to extend :ref:`IPROTO <box_protocol>` functionality from the Lua libraries.
+It allows you to extend the :ref:`IPROTO <box_protocol>` functionality from Lua.
 With this submodule, you can:
 
 *   :ref:`parse the unknown IPROTO requests types <reference_lua-box_iproto_override>`
 *   :ref:`send arbitrary IPROTO packets <reference_lua-box_iproto_send>`
-*   :ref:`override the behavior <reference_lua-box_iproto_override>` of the existing request types in the binary protocol
+*   :ref:`override the behavior <reference_lua-box_iproto_override>` of the existing and unknown request types in the binary protocol
 
 The submodule exports all IPROTO :ref:`constants <internals-box_protocol>` and :ref:`features <internals-iproto-keys-features>` to Lua.
 
@@ -61,7 +61,7 @@ The submodule exports:
 
 **Example**
 
-The example converts the feature names from the ``box.iproto.protocol_features`` set into codes:
+The example converts the feature names from ``box.iproto.protocol_features`` set into codes:
 
 ..  code-block:: lua
 
@@ -89,7 +89,7 @@ Handling the unknown IPROTO request types
 Every IPROTO request has a static handler.
 That is, before version :doc:`2.11.0 </release/2.11.0>`, any unknown request raised an error.
 Since :doc:`2.11.0 </release/2.11.0>`, a new request type is introduced -- :ref:`IPROTO_UNKNOWN <internals-iproto-keys-unknown>`.
-This type is used to override the handlers of the unknown IPROTO requests types. For details, see
+This type is used to override the handlers of the unknown IPROTO request types. For details, see
 :ref:`box.iproto.override() <reference_lua-box_iproto_override>` and :ref:`box_iproto_override <box_box_iproto_override>` functions.
 
 ..  _box_iproto-reference:

doc/reference/reference_lua/box_iproto/override.rst

@@ -1,4 +1,4 @@
-.. _reference_lua-box_iproto_override:
+..  _reference_lua-box_iproto_override:
 
 box.iproto.override()
 =====================
@@ -13,31 +13,32 @@ box.iproto.override()
     :param number request_type: a request type code. Possible values:
 
                                 *   a type code from :ref:`box.iproto.type <reference_lua-box_iproto_type>` (except
-                                    ``box.iproto.type.UNKNOWN``) -- override the existing request type.
+                                    ``box.iproto.type.UNKNOWN``) -- override the existing request type handler.
 
-                                *   ``box.iproto.type.UNKNOWN`` -- override an unknown request type.
+                                *   ``box.iproto.type.UNKNOWN`` -- override the handler of unknown request types.
 
     :param function handler: IPROTO request handler.
                              The signature of a handler function: ``function(sid, header, body)``, where
 
                              *  ``sid`` (number): current IPROTO session identifier (see :ref:`box.session.id() <box_session-id>`)
-                             *  ``header`` (userdata): a request header encoded as :ref:`msgpack_object <msgpack-object-methods>`
-                             *  ``body`` (userdata): a request body encoded as :ref:`msgpack_object <msgpack-object-methods>`
+                             *  ``header`` (userdata): a request header encoded as a :ref:`msgpack_object <msgpack-object-methods>`
+                             *  ``body`` (userdata): a request body encoded as a :ref:`msgpack_object <msgpack-object-methods>`
 
-                             Returns ``true`` on success, otherwise ``false``. In case of failure, there is a fallback
-                             to the system handler.
+                             Returns ``true`` on success, otherwise ``false``. On ``false``, there is a fallback
+                             to the default handler. Also, you can indicate an error by throwing an exception.
+                             In this case, the return value is ``false``, but this does not always means a failure.
 
                              To reset the request handler, set the ``handler`` parameter to ``nil``.
 
     :return: none
 
     **Possible errors:**
 
-    If the Lua handler throws an exception, the behavior is similar to a remote procedure call.
+    If a Lua handler throws an exception, the behavior is similar to that of a remote procedure call.
     The following errors are returned to the client over IPROTO (see `src/lua/utils.h <https://github.com/tarantool/tarantool/blob/dec0e0221e183fa972efa65bb0fb658112f2196f/src/lua/utils.h#L366-L371>`__):
 
-    *   :errcode:`ER_PROC_LUA` -- the exception is thrown, diagnostic is not set.
-    *   diagnostics from ``src/box/errcode.h`` -- the exception is thrown, diagnostic is set.
+    *   :errcode:`ER_PROC_LUA` -- an exception is thrown from a Lua handler, diagnostic is not set.
+    *   diagnostics from ``src/box/errcode.h`` -- an exception is thrown, diagnostic is set.
 
     For details, see `src/box/errcode.h <https://github.com/tarantool/tarantool/blob/master/src/box/errcode.h>`__.
 

doc/reference/reference_lua/box_iproto/send.rst

@@ -62,7 +62,3 @@ box.iproto.send()
                                            sync = 10,
                                            schema_version = box.info.schema_version}))
 
-
-
-
-