Clarify info in the box.session module:

- Update description in `box.session.su()`, `box.session.user()`, and `box.session.euid()`
- Add `box.session.effective_user()` page

Fixes #5062

Author: xuniq

doc/reference/reference_lua/box_session.rst

@@ -39,6 +39,9 @@ Below is a list of all ``box.session`` functions and members.
         *  - :doc:`./box_session/user`
            - Get the current user's name
 
+        *  - :doc:`./box_session/effective_user`
+           - Get the current effective user's name
+
         *  - :doc:`./box_session/type`
            - Get the connection type or cause of action
 

doc/reference/reference_lua/box_session/effective_user.rst

@@ -0,0 +1,12 @@
+.. _box_session-effective_user:
+
+box.session.effective_user()
+============================
+
+.. module:: box.session
+
+.. function:: effective_user()
+
+    :return: the name of the :ref:`current user <authentication-users>`
+
+    :rtype:  string

doc/reference/reference_lua/box_session/euid.rst

@@ -9,7 +9,7 @@ box.session.euid()
 
 .. function:: euid()
 
-    :return: the effective user ID of the :ref:`current user <authentication-users>`.
+    :return: the :ref:`effective user <box_session-effective_user>` ID of the :ref:`current user <authentication-users>`.
 
     This is the same as :doc:`/reference/reference_lua/box_session/uid`, except
     in two cases:

doc/reference/reference_lua/box_session/su.rst

@@ -1,43 +1,55 @@
-
 .. _box_session-su:
 
-================================================================================
 box.session.su()
-================================================================================
+================
 
-.. module:: box.session
+..  module:: box.session
 
-.. function:: su(user-name [, function-to-execute])
+..  function:: su(user-name [, function-to-execute])
 
     Change Tarantool's :ref:`current user <authentication-users>` --
     this is analogous to the Unix command ``su``.
 
-    Or, if function-to-execute is specified,
+    Or, if the `function-to-execute` option is specified,
     change Tarantool's :ref:`current user <authentication-users>`
     temporarily while executing the function --
     this is analogous to the Unix command ``sudo``.
 
     :param string user-name: name of a target user
     :param function-to-execute: name of a function, or definition of a function.
                                 Additional parameters may be passed to
-                                ``box.session.su``, they will be interpreted
-                                as parameters of function-to-execute.
+                                ``box.session.su()``, they will be interpreted
+                                as parameters of `function-to-execute`.
+
+    **Examples:**
+
+    Change Tarantool's current user:
+
+    ..  code-block:: tarantoolsession
+
+        app:instance001> box.session.su('guest')
+        ---
+        ...
+
+    Change Tarantool's current user temporarily:
 
-    **Example:**
+    ..  code-block:: tarantoolsession
 
-    .. code-block:: tarantoolsession
+        app:instance001> function get_current_user() return box.session.user() end
+        ---
+        ...
 
-        tarantool> function f(a) return box.session.user() .. a end
+        app:instance001> box.session.su('guest', get_current_user)
         ---
+        - guest
         ...
 
-        tarantool> box.session.su('guest', f, '-xxx')
+        app:instance001> box.session.su('guest', get_current_user, '-xxx')
         ---
         - guest-xxx
         ...
 
-        tarantool> box.session.su('guest',function(...) return ... end,1,2)
+        app:instance001> box.session.su('guest', function(...) return box.session.user() end)
         ---
-        - 1
-        - 2
+        - guest
         ...

doc/reference/reference_lua/box_session/user.rst

@@ -1,13 +1,16 @@
-
 .. _box_session-user:
 
-================================================================================
 box.session.user()
-================================================================================
+==================
+
+..  module:: box.session
 
-.. module:: box.session
+..  function:: user()
 
-.. function:: user()
+    Return the name of the :ref:`current Tarantool user <authentication-users>`.
+    If the current user is changed temporarily using the :ref:`box.session.su() <box_session-su>` method,
+    `box.session.user()` ignores this change.
+    In this case, `box.session.user()` shows the original current user.
 
     :return: the name of the :ref:`current user <authentication-users>`
 

locale/ru/LC_MESSAGES/reference/reference_lua/box_session/su.po

@@ -10,11 +10,11 @@ msgstr ""
 " аналогично Unix-команде ``su``."
 
 msgid ""
-"Or, if function-to-execute is specified, change Tarantool's :ref:`current "
+"Or, if the `function-to-execute` option is specified, change Tarantool's :ref:`current "
 "user <authentication-users>` temporarily while executing the function -- "
 "this is analogous to the Unix command ``sudo``."
 msgstr ""
-"Или, если указана выполняемая функция (function-to-execute), временное "
+"Или, если указана выполняемая функция (`function-to-execute), временное "
 "изменение :ref:`текущего пользователя <authentication-users>` Tarantool во"
 " время выполнения функции – аналогично Unix-команде ``sudo``."
 
@@ -26,15 +26,15 @@ msgstr "целевое имя пользователя"
 
 msgid ""
 "name of a function, or definition of a function. Additional parameters may "
-"be passed to ``box.session.su``, they will be interpreted as parameters of "
-"function-to-execute."
+"be passed to ``box.session.su()``, they will be interpreted as parameters of "
+"`function-to-execute`."
 msgstr ""
-"имя функции или определение функции. Дополнительные параметры могут "
-"передаваться в ``box.session.su``, они будут интерпретироваться как "
+"имя функции или определение функции. Дополнительные параметры, переданные "
+"в ``box.session.su``, интерпретируются как "
 "параметры выполняемой функции."
 
-msgid "**Example:**"
-msgstr "**Пример:**"
+msgid "**Examples:**"
+msgstr "**Примеры:**"
 
 msgid ""
 "tarantool> function f(a) return box.session.user() .. a end\n"