Credentials: update per TW review - update reference

Author: andreyaksenov

doc/reference/reference_lua/box_schema/role_create.rst

@@ -22,7 +22,10 @@ box.schema.role.create()
 
     **Example:**
 
-    .. code-block:: lua
+    ..  literalinclude:: /code_snippets/test/access_control/grant_roles_test.lua
+        :language: lua
+        :start-after: Create roles
+        :end-before: End: Create roles
+        :dedent:
 
-        box.schema.role.create('Accountant')
-        box.schema.role.create('Accountant', {if_not_exists = false})
+    See also: :ref:`access_control_roles`.

doc/reference/reference_lua/box_schema/role_drop.rst

@@ -18,6 +18,10 @@ box.schema.role.drop()
 
     **Example:**
 
-    .. code-block:: lua
+    ..  literalinclude:: /code_snippets/test/access_control/grant_roles_test.lua
+        :language: lua
+        :start-after: Dropping a role
+        :end-before: End: Dropping a role
+        :dedent:
 
-        box.schema.role.drop('Accountant')
+    See also: :ref:`access_control_roles`.

doc/reference/reference_lua/box_schema/role_exists.rst

@@ -13,8 +13,4 @@ box.schema.role.exists()
     :param string role-name: the name of the role
     :rtype: bool
 
-    **Example:**
-
-    .. code-block:: lua
-
-        box.schema.role.exists('Accountant')
+    See also: :ref:`access_control_roles_info`.

doc/reference/reference_lua/box_schema/role_grant.rst

@@ -12,29 +12,28 @@ box.schema.role.grant()
 
     Grant :ref:`privileges <authentication-owners_privileges>` to a role.
 
-    :param string role-name: the name of the role.
-    :param string privilege: 'read' or 'write' or 'execute' or 'create' or
-                             'alter' or 'drop' or a combination.
-    :param string object-type: 'space' or 'function' or 'sequence' or 'role'.
-    :param string object-name: the name of a function or space or sequence or role.
+    :param string role-name: the name of the role
+    :param string privilege: one or more :ref:`privileges <access_control_list_privileges>` to grant to the role (for example, ``read`` or ``read,write``)
+    :param string object-type: a database :ref:`object type <access_control_list_objects>` to grant privileges to (for example, ``space``, ``role``, or ``function``)
+    :param string object-name: the name of a function or space or sequence or role
     :param table option: ``if_not_exists`` = ``true|false`` (default = ``false``) - boolean;
                          ``true`` means there should be no error if the role already
-                         has the privilege.
+                         has the privilege
 
     The role must exist, and the object must exist.
 
-    **Variation:** instead of ``object-type, object-name`` say 'universe'
+    **Variation:** instead of ``object-type, object-name`` say ``universe``
     which means 'all object-types and all objects'. In this case, object name is omitted.
 
     **Variation:** instead of ``privilege, object-type, object-name`` say
     ``role-name`` -- to grant a role to a role.
 
     **Example:**
 
-    .. code-block:: lua
+    ..  literalinclude:: /code_snippets/test/access_control/grant_roles_test.lua
+        :language: lua
+        :start-after: Grant read/write privileges to a role
+        :end-before: Grant write privileges to a role
+        :dedent:
 
-        box.schema.role.grant('Accountant', 'read', 'space', 'tester')
-        box.schema.role.grant('Accountant', 'execute', 'function', 'f')
-        box.schema.role.grant('Accountant', 'read,write', 'universe')
-        box.schema.role.grant('public', 'Accountant')
-        box.schema.role.grant('role1', 'role2', nil, nil, {if_not_exists=false})
+    See also: :ref:`access_control_roles`.

doc/reference/reference_lua/box_schema/role_info.rst

@@ -12,8 +12,4 @@ box.schema.role.info()
 
     :param string role-name: the name of the role.
 
-    **Example:**
-
-    .. code-block:: lua
-
-        box.schema.role.info('Accountant')
+    See also: :ref:`access_control_roles_info`.

doc/reference/reference_lua/box_schema/role_revoke.rst

@@ -10,26 +10,18 @@ box.schema.role.revoke()
 
     Revoke :ref:`privileges <authentication-owners_privileges>` from a role.
 
-    :param string role-name: the name of the role.
-    :param string privilege: 'read' or 'write' or 'execute' or 'create' or
-                             'alter' or 'drop' or a combination.
-    :param string object-type: 'space' or 'function' or 'sequence' or 'role'.
-    :param string object-name: the name of a function or space or sequence or role.
+    :param string role-name: the name of the role
+    :param string privilege: one or more :ref:`privileges <access_control_list_privileges>` to revoke from the role (for example, ``read`` or ``read,write``)
+    :param string object-type: a database :ref:`object type <access_control_list_objects>` to revoke privileges from (for example, ``space``, ``role``, or ``function``)
+    :param string object-name: the name of a database object to revoke privileges from
 
     The role must exist, and the object must exist,
     but it is not an error if the role does not have the privilege.
 
-    **Variation:** instead of ``object-type, object-name`` say 'universe'
+    **Variation:** instead of ``object-type, object-name`` say ``universe``
     which means 'all object-types and all objects'.
 
     **Variation:** instead of ``privilege, object-type, object-name`` say
     ``role-name``.
 
-    **Example:**
-
-    .. code-block:: lua
-
-        box.schema.role.revoke('Accountant', 'read', 'space', 'tester')
-        box.schema.role.revoke('Accountant', 'execute', 'function', 'f')
-        box.schema.role.revoke('Accountant', 'read,write', 'universe')
-        box.schema.role.revoke('public', 'Accountant')
+    See also: :ref:`access_control_roles`.

doc/reference/reference_lua/box_schema/user_create.rst

@@ -21,7 +21,7 @@ box.schema.user.create()
     * ``password`` (default = '') - string; the ``password`` = *password*
       specification is good because in a :ref:`URI <index-uri>`
       (Uniform Resource Identifier) it is usually illegal to include a
-      user-name without a password.
+      username without a password.
 
     .. NOTE::
 
@@ -34,8 +34,10 @@ box.schema.user.create()
 
     **Examples:**
 
-    .. code-block:: lua
+    ..  literalinclude:: /code_snippets/test/access_control/grant_user_privileges_test.lua
+        :language: lua
+        :start-after: Create a user with a password
+        :end-before: End: Create a user with a password
+        :dedent:
 
-        box.schema.user.create('testuser')
-        box.schema.user.create('testuser', {password = 'foobar'})
-        box.schema.user.create('testuser', {if_not_exists = false})
+    See also: :ref:`access_control_users`.

doc/reference/reference_lua/box_schema/user_drop.rst

@@ -6,20 +6,23 @@ box.schema.user.drop()
 
 .. module:: box.schema
 
-.. function:: box.schema.user.drop(user-name [, {options}])
+.. function:: box.schema.user.drop(username [, {options}])
 
     Drop a user.
     For explanation of how Tarantool maintains user data, see
     section :ref:`Users <authentication-users>` and reference on
     :ref:`_user <box_space-user>` space.
 
-    :param string user-name: the name of the user
+    :param string username: the name of the user
     :param table options: ``if_exists`` = ``true|false`` (default = ``false``) - boolean;
                           ``true`` means there should be no error if the user does not exist.
 
     **Examples:**
 
-    .. code-block:: lua
+    ..  literalinclude:: /code_snippets/test/access_control/grant_user_privileges_test.lua
+        :language: lua
+        :start-after: Drop a user
+        :end-before: End: Drop a user
+        :dedent:
 
-        box.schema.user.drop('Lena')
-        box.schema.user.drop('Lena',{if_exists=false})
+    See also: :ref:`access_control_users`.

doc/reference/reference_lua/box_schema/user_exists.rst

@@ -6,18 +6,14 @@ box.schema.user.exists()
 
 .. module:: box.schema
 
-.. function:: box.schema.user.exists(user-name)
+.. function:: box.schema.user.exists(username)
 
     Return ``true`` if a user exists; return ``false`` if a user does not exist.
     For explanation of how Tarantool maintains user data, see
     section :ref:`Users <authentication-users>` and reference on
     :ref:`_user <box_space-user>` space.
 
-    :param string user-name: the name of the user
+    :param string username: the name of the user
     :rtype: bool
 
-    **Example:**
-
-    .. code-block:: lua
-
-        box.schema.user.exists('Lena')
+    See also: :ref:`access_control_user_info`.

doc/reference/reference_lua/box_schema/user_grant.rst

@@ -6,32 +6,32 @@ box.schema.user.grant()
 
 .. module:: box.schema
 
-.. function:: box.schema.user.grant(user-name, privileges, object-type, object-name[, {options} ])
-              box.schema.user.grant(user-name, privileges, 'universe'[, nil, {options} ])
-              box.schema.user.grant(user-name, role-name[, nil, nil, {options} ])
+.. function:: box.schema.user.grant(username, privileges, object-type, object-name[, {options} ])
+              box.schema.user.grant(username, privileges, 'universe'[, nil, {options} ])
+              box.schema.user.grant(username, role-name[, nil, nil, {options} ])
 
     Grant :ref:`privileges <authentication-owners_privileges>` to a user or
     to another role.
 
-    :param string   user-name: the name of a user to grant privileges to
-    :param string  privileges: one or more privileges to grant to the user (for example, `read` or `read,write`)
-    :param string object-type: a database object type to grant privileges to (for example, `space`, `role`, or `function`)
+    :param string   username: the name of a user to grant privileges to
+    :param string  privileges: one or more :ref:`privileges <access_control_list_privileges>` to grant to the user (for example, ``read`` or ``read,write``)
+    :param string object-type: a database :ref:`object type <access_control_list_objects>` to grant privileges to (for example, ``space``, ``role``, or ``function``)
     :param string object-name: the name of a database object to grant privileges to
     :param string   role-name: the name of a role to grant to the user
     :param table      options: ``grantor``, ``if_not_exists``
 
     If :samp:`'function','{object-name}'` is specified, then a _func tuple with
     that object-name must exist.
 
-    **Variation:** instead of ``object-type, object-name`` say 'universe' which
+    **Variation:** instead of ``object-type, object-name`` say ``universe`` which
     means 'all object-types and all objects'. In this case, object name is omitted.
 
     **Variation:** instead of ``privilege, object-type, object-name`` say
     ``role-name`` (see section :ref:`Roles <authentication-roles>`).
 
     **Variation:** instead of
-    :samp:`box.schema.user.grant('{user-name}','usage,session','universe',nil,` :code:`{if_not_exists=true})`
-    say :samp:`box.schema.user.enable('{user-name}')`.
+    :samp:`box.schema.user.grant('{username}','usage,session','universe',nil,` :code:`{if_not_exists=true})`
+    say :samp:`box.schema.user.enable('{username}')`.
 
     The possible options are:
 
@@ -41,11 +41,10 @@ box.schema.user.grant()
 
     **Example:**
 
-    .. code-block:: lua
+    ..  literalinclude:: /code_snippets/test/access_control/grant_user_privileges_test.lua
+        :language: lua
+        :start-after: Grant privileges to the specified user
+        :end-before: End: Grant privileges to the specified user
+        :dedent:
 
-        box.schema.user.grant('Lena', 'read', 'space', 'tester')
-        box.schema.user.grant('Lena', 'execute', 'function', 'f')
-        box.schema.user.grant('Lena', 'read,write', 'universe')
-        box.schema.user.grant('Lena', 'Accountant')
-        box.schema.user.grant('Lena', 'read,write,execute', 'universe')
-        box.schema.user.grant('X', 'read', 'universe', nil, {if_not_exists=true})
+    See also: :ref:`access_control_users`.

doc/reference/reference_lua/box_schema/user_info.rst

@@ -6,23 +6,14 @@ box.schema.user.info()
 
 .. module:: box.schema
 
-.. function:: box.schema.user.info([user-name])
+.. function:: box.schema.user.info([username])
 
     Return a description of a user's :ref:`privileges <authentication-owners_privileges>`.
 
-    :param string user-name: the name of the user.
-                             This is optional; if it is not
-                             supplied, then the information
-                             will be for the user who is
-                             currently logged in.
+    :param string username: the name of the user.
+                            This is optional; if it is not
+                            supplied, then the information
+                            will be for the user who is
+                            currently logged in.
 
-    **Example:**
-
-    .. code-block:: tarantoolsession
-
-        tarantool> box.schema.user.info('admin')
-        ---
-        - - - read,write,execute,session,usage,create,drop,alter,reference,trigger,insert,update,delete
-            - universe
-            -
-        ...
+    See also: :ref:`access_control_user_info`.

doc/reference/reference_lua/box_schema/user_passwd.rst

@@ -6,22 +6,25 @@ box.schema.user.passwd()
 
 .. module:: box.schema
 
-.. function:: box.schema.user.passwd([name,] new_password)
+.. function:: box.schema.user.passwd([username,] password)
 
     Sets a password for a currently logged in or a specified user:
 
-    *   A currently logged in user can change their password using
-        ``box.schema.user.passwd(new_password)``.
+    *   A currently logged-in user can change their password using
+        ``box.schema.user.passwd(password)``.
 
     *   An administrator can change the password of another user with
-        ``box.schema.user.passwd(name, new_password)``.
+        ``box.schema.user.passwd(username, password)``.
 
-    :param string user-name: name
-    :param string password: new_password
+    :param string username: a username
+    :param string password: a new password
 
     **Example:**
 
-    .. code-block:: lua
+    ..  literalinclude:: /code_snippets/test/access_control/grant_user_privileges_test.lua
+        :language: lua
+        :start-after: Set a password for the specified user
+        :end-before: End: Set a password for the specified user
+        :dedent:
 
-        box.schema.user.passwd('foobar')
-        box.schema.user.passwd('testuser', 'foobar')
+    See also: :ref:`access_control_users`.

doc/reference/reference_lua/box_schema/user_revoke.rst

@@ -6,19 +6,18 @@ box.schema.user.revoke()
 
 .. module:: box.schema
 
-.. function:: box.schema.user.revoke(user-name, privileges, object-type, object-name[, {options} ])
-              box.schema.user.revoke(user-name, privileges, 'universe'[, nil, {options} ])
-              box.schema.user.revoke(user-name, role-name[, nil, nil, {options} ])
+.. function:: box.schema.user.revoke(username, privileges, object-type, object-name[, {options} ])
+              box.schema.user.revoke(username, privileges, 'universe'[, nil, {options} ])
+              box.schema.user.revoke(username, role-name[, nil, nil, {options} ])
 
     Revoke :ref:`privileges <authentication-owners_privileges>` from a user
     or from another role.
 
-    :param string user-name: the name of the user.
-    :param string privilege: 'read' or 'write' or 'execute' or 'create' or
-                             'alter' or 'drop' or a combination.
-    :param string object-type: 'space' or 'function' or 'sequence'.
-    :param string object-name: the name of a function or space or sequence.
-    :param table      options: ``if_exists``.
+    :param string username: the name of the user
+    :param string privilege: one or more :ref:`privileges <access_control_list_privileges>` to revoke from the user (for example, ``read`` or ``read,write``)
+    :param string object-type: a database :ref:`object type <access_control_list_objects>` to revoke privileges from (for example, ``space``, ``role``, or ``function``)
+    :param string object-name: the name of a database object to revoke privileges from
+    :param table      options: ``if_exists``
 
     The user must exist, and the object must exist,
     but if the option setting is ``{if_exists=true}`` then
@@ -31,14 +30,15 @@ box.schema.user.revoke()
     ``role-name`` (see section :ref:`Roles <authentication-roles>`).
 
     **Variation:** instead of
-    :samp:`box.schema.user.revoke('{user-name}','usage,session','universe',nil,` :code:`{if_exists=true})`
-    say :samp:`box.schema.user.disable('{user-name}')`.
+    :samp:`box.schema.user.revoke('{username}','usage,session','universe',nil,` :code:`{if_exists=true})`
+    say :samp:`box.schema.user.disable('{username}')`.
 
     **Example:**
 
-    .. code-block:: lua
+    ..  literalinclude:: /code_snippets/test/access_control/grant_user_privileges_test.lua
+        :language: lua
+        :start-after: Revoke space reading
+        :end-before: End: Revoke space reading
+        :dedent:
 
-        box.schema.user.revoke('Lena', 'read', 'space', 'tester')
-        box.schema.user.revoke('Lena', 'execute', 'function', 'f')
-        box.schema.user.revoke('Lena', 'read,write', 'universe')
-        box.schema.user.revoke('Lena', 'Accountant')
+    See also: :ref:`access_control_users`.