Roles: cosmetics

Author: andreyaksenov

doc/concepts/configuration.rst

@@ -184,7 +184,7 @@ Enabling and configuring roles
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 An application role is a Lua module that implements specific functions or logic.
-You can enable or turn off a specific role for certain instances in a configuration without restarting these instances.
+You can enable or turn off a particular role for certain instances in a configuration without restarting these instances.
 
 This section describes how to enable and configure roles.
 To learn how to develop custom roles, see :ref:`application_roles`.
@@ -240,9 +240,9 @@ Roles and configuration scopes
 ******************************
 
 As the most of configuration options, roles and their configurations can be defined at :ref:`different levels <configuration_scopes>`.
-Given that the ``roles`` option has the ``array`` type and ``roles_cfg`` has the ``map`` type, there are some specifics when applying the configuration:
+Given that the ``roles`` option has the ``array`` type and ``roles_cfg`` has the ``map`` type, there are some specifics of applying the configuration:
 
--   For ``roles``, an instance's role takes precedence over roles defined at another levels.
+-   For ``roles``, an instance's role takes precedence over roles defined at another level.
     In the example below, ``instance001`` has only ``role3``:
 
     ..  code-block:: yaml
@@ -258,7 +258,7 @@ Given that the ``roles`` option has the ``array`` type and ``roles_cfg`` has the
 
 -   For ``roles_cfg``, the following rules are applied:
 
-    -   If a configuration for the same role is provided at different levels, an instance configuration takes precedence over configuration defined at another levels.
+    -   If a configuration for the same role is provided at different levels, an instance configuration takes precedence over the configuration defined at another level.
         In the example below, ``role1.greeting`` is ``'Hi'``:
 
         ..  code-block:: yaml
@@ -275,7 +275,7 @@ Given that the ``roles`` option has the ``array`` type and ``roles_cfg`` has the
                     role1:
                       greeting: 'Hi'
 
-    -   If configurations for different roles are provided at different levels, both configurations are applied at the instance level.
+    -   If the configurations for different roles are provided at different levels, both configurations are applied at the instance level.
         In the example below, ``instance001`` has ``role1.greeting`` set to ``'Hi'`` and ``role2.farewell`` set to ``'Bye'``:
 
         ..  code-block:: yaml

doc/how-to/app/app_roles.rst

@@ -4,7 +4,7 @@ Application roles
 =================
 
 An application role is a Lua module that implements specific functions or logic.
-You can enable or turn off a specific role for certain instances in a :ref:`configuration <configuration>` without restarting these instances.
+You can enable or turn off a particular role for certain instances in a :ref:`configuration <configuration>` without restarting these instances.
 A role is run when a configuration is loaded or reloaded.
 
 Roles can be divided into the following groups:
@@ -14,7 +14,7 @@ Roles can be divided into the following groups:
 -   Roles provided by third-party Lua modules.
     For example, the `CRUD <https://github.com/tarantool/crud>`__ module provides the ``roles.crud-storage`` and ``roles.crud-router`` roles that enable CRUD operations in a sharded cluster.
 -   Custom roles that are developed as a part of a cluster application.
-    For example, you create a custom role to define a stored procedure or implement a supplementary service, such as an email notifier or a replicator.
+    For example, you can create a custom role to define a stored procedure or implement a supplementary service, such as an email notifier or a replicator.
 
 This section describes how to develop custom roles.
 To learn how to enable and configure roles, see :ref:`configuration_application_roles`.
@@ -61,12 +61,12 @@ Creating a custom role
 Overview
 ~~~~~~~~
 
-The main steps of creating a custom role might include the following steps:
+Creating a custom role includes the following steps:
 
 1.  Define a function that validates a role's configuration.
 2.  Define a function that applies a validated configuration.
 3.  Define a function that stops a role.
-4.  (Optional) Define roles from which a custom role depends on.
+4.  (Optional) Define roles from which this custom role depends on.
 
 As a result, a role's module should return an object that has corresponding functions and fields specified:
 
@@ -104,7 +104,7 @@ In the example below, the ``validate()`` function is used to validate the ``gree
     :end-before: local function apply
     :dedent:
 
-If the configuration is not valid, ``validate`` reports an unrecoverable error by throwing an error object.
+If the configuration is not valid, ``validate()`` reports an unrecoverable error by throwing an error object.
 
 
 
@@ -114,8 +114,8 @@ If the configuration is not valid, ``validate`` reports an unrecoverable error b
 Applying a role configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To apply a validated configuration, define the :ref:`apply([cfg]) <roles_api_reference_apply>` function.
-As the ``validate()`` function, ``apply()`` also provides access to a role's configuration using the ``cfg`` argument.
+To apply the validated configuration, define the :ref:`apply([cfg]) <roles_api_reference_apply>` function.
+As the ``validate()`` function, ``apply()`` provides access to a role's configuration using the ``cfg`` argument.
 
 In the example below, the ``apply()`` function uses the :ref:`log <log-module>` module to write a role's configuration value to the log:
 
@@ -248,7 +248,7 @@ Roles' life cycle includes the stages described below.
 
 2)  *Stopping roles*
 
-    This stage is in effect on configuration reload when a role is removed from configuration for the given instance.
+    This stage is in effect on configuration reload when a role is removed from a configuration for the given instance.
     Note that all ``stop()`` calls are performed before any ``validate()`` or ``apply()`` calls.
     This means that old roles are stopped first and only then new roles are started.
 
@@ -268,7 +268,7 @@ Roles' life cycle includes the stages described below.
 All role's functions report an unrecoverable error by throwing an error object.
 If an error is thrown in any phase, applying a configuration is stopped.
 If starting or stopping a role throws an error, no roles are stopped or started afterward.
-An error is catched and shown in :ref:`config:info() <config_api_reference_info>` in the ``alerts`` section.
+An error is caught and shown in :ref:`config:info() <config_api_reference_info>` in the ``alerts`` section.
 
 
 .. _roles_life_cycle_dependencies_specifics:
@@ -285,7 +285,7 @@ Suppose, there are two independent roles (``role1``, ``role2``) and three roles
         └─── role4
                  └─── role5
 
-The roles are enable in a configuration as follows:
+The roles are enabled in a configuration as follows:
 
 ..  code-block:: yaml
 
@@ -298,13 +298,13 @@ In this case, ``validate()`` and ``apply()`` for these roles are executed in the
     role1 -> role2 -> role5 -> role4 -> role3
 
 Roles removed from a configuration are stopped in the order reversed to the order they are specified in a configuration, taking into account the dependencies.
-If all roles except ``role1`` are removed from the configuration above, ...
+Suppose, all roles except ``role1`` are removed from the configuration above:
 
 ..  code-block:: yaml
 
     roles: [ role1 ]
 
-... ``stop()`` functions for removed roles are executed in the following order:
+After reloading a configuration, ``stop()`` functions for the removed roles are executed in the following order:
 
 ..  code-block:: none
 
@@ -326,7 +326,7 @@ The example below shows how to enable the custom ``greeter`` role for ``instance
     :end-at: greeter
     :dedent:
 
-You can define the ``validate()``, ``apply()``, and ``stop()`` functions in the role's code as follows:
+The implementation of this role looks as follows:
 
 ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role/greeter.lua
     :language: lua
@@ -349,7 +349,7 @@ The example below shows how to enable the custom ``greeter`` role for ``instance
     :end-at: greeting
     :dedent:
 
-You can define the ``validate()``, ``apply()``, and ``stop()`` functions in the role's code as follows:
+The implementation of this role looks as follows:
 
 ..  literalinclude:: /code_snippets/snippets/config/instances.enabled/application_role_cfg/greeter.lua
     :language: lua