Update net.box options (#2912)

* Update net_box-connect

* Add details to required_protocol_features option

* Improve the style

* Add a table to required_protocol_features

* Move the connect_timeout option

* Change table headers

* Restructure net.box options

* Remove spaces

* Edit parameters of net_box.new

* Fixed remarks

* Add commas

* Add require('net.box') to the example

* Fix an error

Author: rindblack15

doc/reference/reference_lua/net_box.rst

@@ -11,7 +11,7 @@ Module net.box
 The ``net.box`` module contains connectors to remote database systems. One
 variant, to be discussed later, is for connecting to MySQL or MariaDB or PostgreSQL
 (see :ref:`SQL DBMS modules <dbms_modules>` reference). The other variant, which
-is discussed in this section, is for connecting to Tarantool server instances via a
+is discussed in this section, is for connecting to Tarantool server instances via a 
 network.
 
 You can call the following methods:
@@ -147,80 +147,118 @@ Below is a list of all ``net.box`` functions.
 
 .. function:: connect(URI [, {option[s]}])
 
+    The names ``connect()`` and ``new()`` are synonyms: ``connect()`` is 
+    preferred; ``new()`` is retained for backward compatibility. For more 
+    information, see the description of ``net_box.new()`` below.
+
 .. _net_box-new:
 
 .. function:: new(URI [, {option[s]}])
 
-    .. NOTE::
-
-       The names ``connect()`` and ``new()`` are synonyms: ``connect()`` is
-       preferred; ``new()`` is retained for backward compatibility.
-
     Create a new connection. The connection is established on demand, at the
     time of the first request. It can be re-established automatically after a
     disconnect (see ``reconnect_after`` option below).
     The returned ``conn`` object supports methods for making remote requests,
     such as select, update or delete.
 
-    Possible options:
-
-    * `user/password`: you have two ways to connect to a remote host:
-      using :ref:`URI <index-uri>` or using the options `user` and `password`. For
-      example, instead of ``connect('username:userpassword@localhost:33301')`` you
-      can write ``connect('localhost:33301', {user = 'username', password='userpassword'})``.
-
-    * `wait_connected`: by default, connection creation is blocked until the connection is established,
-      but passing ``wait_connected=false`` makes it return immediately. Also, passing a timeout
-      makes it wait before returning (e.g. ``wait_connected=1.5`` makes it wait at most 1.5 seconds).
-
-      .. NOTE::
-
-         If ``reconnect_after`` is greater than zero, then ``wait_connected`` ignores transient failures.
-         The wait completes once the connection is established or is closed explicitly.
-
-    * `reconnect_after`: if ``reconnect_after`` is greater than zero, then a ``net.box`` instance
-      will try to reconnect if a connection is broken or if a connection attempt fails.
-      This makes transient network failures become transparent to the application.
-      Reconnect happens automatically in the background, so requests that
-      initially fail due to connectivity loss are transparently retried.
-      The number of retries is unlimited, connection attempts are made after each
-      specified interval (for example ``reconnect_after=5`` means try to reconnect every 5 seconds).
-      When a connection is explicitly closed, or when the Lua garbage collector
-      removes it, then reconnect attempts stop.
-      The default value of ``reconnect_after``, as with other ``connect`` options, is ``nil``.
-
-    * `call_16`: [since 1.7.2] by default, ``net.box`` connections comply with a new
-      binary protocol command for CALL, which is not backward compatible with previous versions.
-      The new CALL no longer restricts a function to returning an array of tuples
-      and allows returning an arbitrary MsgPack/JSON result, including scalars, nil and void (nothing).
-      The old CALL is left intact for backward compatibility.
-      It will be removed in the next major release.
-      All programming language drivers will be gradually changed to use the new CALL.
-      To connect to a Tarantool instance that uses the old CALL, specify ``call_16=true``.
-
-    * `console`: depending on the option's value, the connection supports different methods
-      (as if instances of different classes were returned). With ``console = true``, you can use
-      ``conn`` methods ``close()``, ``is_connected()``, ``wait_state()``, ``eval()`` (in this case, both
-      binary and Lua console network protocols are supported). With ``console = false`` (default), you can
-      also use ``conn`` database methods (in this case, only the binary protocol is supported).
-      Deprecation notice: ``console = true`` is deprecated, users should use
-      :ref:`console.connect() <console-connect>` instead.
-
-    * `connect_timeout`: number of seconds to wait before returning "error: Connection timed out".
-
     :param string URI: the :ref:`URI <index-uri>` of the target for the connection
-    :param options: possible options are `user`, `password`, `wait_connected`,
-                    `reconnect_after`, `call_16`, `console` and `connect_timeout`
+    :param options: the supported options are shown below:
+    
+        *   ``user/password``: two options to connect to a remote host other than through 
+            :ref:`URI <index-uri>`. For example, instead of ``connect('username:userpassword@localhost:3301')`` 
+            you can write ``connect('localhost:3301', {user = 'username', password='userpassword'})``.
+
+        *   ``wait_connected``: a connection timeout. By default, the connection is blocked until the connection 
+            is established, but if you specify ``wait_connected=false``, the connection returns immediately. 
+            If you specify this timeout, it will wait before returning (``wait_connected=1.5`` makes it wait at most 1.5 seconds).
+
+            .. NOTE::
+
+                 If ``reconnect_after`` is greater than zero, then ``wait_connected`` ignores transient failures.
+                 The wait completes once the connection is established or is closed explicitly.
+
+
+        *   ``reconnect_after``: a number of seconds to wait before reconnecting. 
+            The default value, as with the other ``connect`` options, is ``nil``. If ``reconnect_after`` 
+            is greater than zero, then a ``net.box`` instance will attempt to reconnect if a connection 
+            is lost or a connection attempt fails. This makes transient network failures transparent to the application. 
+            Reconnection happens automatically in the background, so requests that initially fail due to connection drops 
+            fail, are transparently retried. The number of retries is unlimited, connection retries are made after 
+            any specified interval (for example, ``reconnect_after=5`` means that reconnect attempts are made every 5 seconds). 
+            When a connection is explicitly closed or when the Lua garbage collector removes it, then reconnect attempts stop. 
+        
+
+        *   ``call_16``: [since 1.7.2] a new binary protocol command for CALL in ``net.box`` connections by default. 
+            The new CALL is not backward compatible with previous versions. It no longer restricts a function to 
+            returning an array of tuples and allows returning an arbitrary MsgPack/JSON result, 
+            including scalars, nil and void (nothing). The old CALL is left intact for backward compatibility. 
+            It will not be present in the next major release. All programming language drivers will gradually be switched 
+            to the new CALL. To connect to a Tarantool instance that uses the old CALL, specify ``call_16=true``.
+
+        *   ``console``: an option to use different connection support methods (as if instances of different 
+            classes are returned). With ``console = true``, you can use the ``conn`` methods ``close()``, 
+            ``is_connected()``, ``wait_state()``, ``eval()`` (in this case both binary and Lua console 
+            network protocols are supported). 
+            With ``console = false`` (default), you can also use ``conn`` database methods (in this case only the 
+            binary protocol is supported). Deprecation note: ``console = true`` is deprecated, users should use 
+            :ref:`console.connect() <console-connect>` instead.
+
+        *   ``connect_timeout``: a number of seconds to wait before returning "error: Connection timed out".
+
+        *   ``required_protocol_version``: a minimum version of the :ref:`IPROTO protocol <box_protocol-id>` 
+            supported by the server. If the version of the :ref:`IPROTO protocol <box_protocol-id>` supported 
+            by the server is lower than specified, the connection will fail with an error message. 
+            With ``required_protocol_version = 1``, all connections fail where the :ref:`IPROTO protocol <box_protocol-id>` 
+            version is lower than ``1``.  
+
+        *   ``required_protocol_features``: specified :ref:`IPROTO protocol features <box_protocol-id>` supported by the server. 
+            You can specify one or more ``net.box`` features from the table below. If the server does not 
+            support the specified features, the connection will fail with an error message. 
+            With ``required_protocol_features = {'transactions'}``, all connections fail where the 
+            server has ``transactions: false``.
+        
+    ..  container:: table
+
+    ..  list-table::
+        :widths: 26 29 25 20
+        :header-rows: 1
+
+        *   -   net.box feature
+            -   Use
+            -   IPROTO feature ID
+            -   IPROTO protocol versions with the net.box feature support
+        *   -   ``streams``  
+            -   Requires streams support on the server
+            -   IPROTO_FEATURE_STREAMS 
+            -   1 and newer
+        *   -   ``transactions``
+            -   Requires transactions support on the server
+            -   IPROTO_FEATURE_TRANSACTIONS   
+            -   1 and newer
+        *   -   ``error_extension``
+            -   Requires support for :ref:`MP_ERROR <msgpack_ext-error>` MsgPack extension on the server
+            -   IPROTO_FEATURE_ERROR_EXTENSION   
+            -   2 and newer
+        *   -   ``watchers``
+            -   Requires remote watchers support on the server
+            -   IPROTO_FEATURE_WATCHERS   
+            -   3 and newer      
+            
+    To learn more about IPROTO features, see :ref:`IPROTO_ID <box_protocol-id>`.
+ 
     :return: conn object
     :rtype:  userdata
 
     **Examples:**
 
     .. code-block:: lua
 
+        net_box = require('net.box')
+        
         conn = net_box.connect('localhost:3301')
         conn = net_box.connect('127.0.0.1:3302', {wait_connected = false})
         conn = net_box.connect('127.0.0.1:3303', {reconnect_after = 5, call_16 = true})
+        conn = net_box.connect('127.0.0.1:3304', {required_protocol_version = 4, required_protocol_features = {'transactions', 'streams'}, })
 
 .. _net_box-self:
 
@@ -624,7 +662,7 @@ Below is a list of all ``net.box`` functions.
 
     .. _conn-new_stream:
 
-    .. method:: stream([options])
+    .. method:: new_stream([options])
 
         Create a stream.