upsert, correction

doc/sphinx/book/box/box_index.rst

@@ -495,9 +495,7 @@ API is a direct binding to corresponding methods of index objects of type
         :param lua-value key: key to be matched against the index key
         :param table {operator, field_no, value}: update opearations (see: func:`box.space...update() <space_object.update>`)
 
-        :return: the updated or inserted tuple.
-        :rtype:  tuple
-
+        :return: null.
 
     .. function:: delete(key)
 

doc/sphinx/book/box/box_space.rst

@@ -372,7 +372,10 @@ A list of all ``box.space`` functions follows, then comes a list of all
         :code:`{{operator, field_no, value}, ...}` parameter is used.
         If there is no existing tuple which matches :code:`key`, then the
         request has the same effect as :ref:`insert <box_insert>` and the
-        :code:`{tuple}` parameter is used.
+        :code:`{tuple}` parameter is used. However, unlike :code:`insert` or
+        :code:`update`, :code:`upsert` will not read a tuple and perform
+        error checks before returning -- this is a design feature which
+        enhances throughput but requires more caution on the part of the user.
 
         :param space_object space-object:
         :param lua-value key: primary-key field values, must be passed as a Lua
@@ -383,8 +386,8 @@ A list of all ``box.space`` functions follows, then comes a list of all
                 field number can be negative, meaning the position from the
                 end of tuple (#tuple + negative field number + 1).
 
-        :return: the updated or inserted tuple.
-        :rtype:  tuple
+        :return: null.
+
 
         Possible errors: it is illegal to modify a primary-key field.
 

doc/sphinx/book/box/index.rst

@@ -424,8 +424,8 @@ Data manipulation
 The basic "data-manipulation" requests are:
 :codenormal:`insert`, :codenormal:`replace`, :codenormal:`update`, :codenormal:`upsert`,
 :codenormal:`delete`, :codenormal:`select`.
-They all are part of the :codenormal:`box` library.
-They all may return data. Usually both inputs and outputs may be Lua tables.
+All of them are part of the :codenormal:`box` library.
+Most of them may return data. Usually both inputs and outputs may be Lua tables.
 
 The Lua syntax for data-manipulation functions can vary.
 Here are examples of the variations with :codenormal:`select` examples;