Update documentation and code snippets

docs/index.rst

@@ -19,7 +19,7 @@ Argenta
 
 Argenta предназначена для создания приложений, работающих в собственном контексте (scope). Это означает, что приложение запускается один раз и создаёт интерактивную сессию, похожую на Python REPL или MySQL консоль. При запуске пользователь входит в эту сессию, где ему доступна вся реализованная вами функциональность.
 
-Один из ключевых принципов библиотеки — цикличность. После выполнения команды пользователь остаётся в интерактивной сессии и имеет доступ к созданной вами функциональности, в отличие от таких библиотек, как ``argparse``, ``click`` и ``typer``. Выход из сессии контролируется пользователем.
+Один из ключевых принципов библиотеки — цикличность. После выполнения команды пользователь остаётся в интерактивной сессии, в отличие от таких библиотек, как ``argparse``, ``click`` и ``typer``, где приложение завершается после каждой команды. Выход из сессии контролируется пользователем.
 
 **Ключевые особенности:**
 

docs/root/api/bridge.rst

@@ -5,7 +5,7 @@ DataBridge
 
 ``DataBridge`` — это сущность, предоставляющая временное хранилище данных, которое существует в рамках одной сессии приложения (от запуска до выхода). Она предназначена для обмена данными между обработчиками.
 
-Основной способ получения доступа к ``DataBridge`` — через ``di``.
+Основной способ получения доступа к ``DataBridge`` — через DI.
 
 .. code-block:: python
    :linenos:
@@ -39,7 +39,7 @@ DataBridge
    .. py:method:: __init__(self, initial_data: dict | None = None)
       :no-index:
 
-      Инициализирует хранилище. При использовании через ``di`` вызывается автоматически.
+      Инициализирует хранилище. При использовании через DI вызывается автоматически.
 
    .. py:method:: update(self, data: dict) -> None
 

docs/root/api/orchestrator/argparser.rst

@@ -44,7 +44,7 @@ ArgParser
 Лучшие практики
 ---------------
 
-Использовать атрибут ``parsed_argspace`` рекомендуется только на этапе настройки приложения. В обработчиках лучшей практикой является получение ``ArgSpace`` через ``di``. Подробнее см. :ref:`здесь <root_dependency_injection>`.
+Использовать атрибут ``parsed_argspace`` рекомендуется только на этапе настройки приложения. В обработчиках лучшей практикой является получение ``ArgSpace`` через DI. Подробнее см. :ref:`здесь <root_dependency_injection>`.
 
 **Пример использования:**
 

docs/root/api/orchestrator/argspace.rst

@@ -85,7 +85,7 @@ InputArgument
 .. literalinclude:: ../../../code_snippets/argspace/snippet.py
    :linenos:
    
-Доступ к аргументам из обработчиков осуществляется с помощью ``di``. Подробнее см. :ref:`здесь <root_dependency_injection>`.
+Доступ к аргументам из обработчиков осуществляется с помощью DI. Подробнее см. :ref:`здесь <root_dependency_injection>`.
 
 **Пример использования:**
 

docs/root/api/orchestrator/index.rst

@@ -3,7 +3,7 @@
 Orchestrator
 ====================
 
-``Orchestrator`` — это высокоуровневый компонент, который конфигурирует и оркестрирует приложение, парсер командной строки, ``di`` и остальные компоненты, находящиеся по иерархии на уровне с ``App``.
+``Orchestrator`` — это высокоуровневый компонент, который конфигурирует и оркестрирует приложение, парсер командной строки, DI и остальные компоненты, находящиеся по иерархии на уровне с ``App``.
 
 В то время как ``App`` отвечает за логику интерактивной сессии (ввод команд, маршрутизация), ``Orchestrator`` подготавливает окружение для его работы и служит точкой входа в приложение.
 
@@ -47,7 +47,7 @@ Orchestrator
 Назначение и использование
 ----------------------------
 
-``Orchestrator`` абстрагирует сложность, связанную с настройкой ``di`` и парсингом стартовых аргументов.
+``Orchestrator`` абстрагирует сложность, связанную с настройкой DI и парсингом стартовых аргументов.
 
 Такой подход разделяет ответственности: ``App`` отвечает за логику интерактивной сессии, а ``Orchestrator`` — за подготовку окружения и запуск приложения.
 

docs/root/dependency_injection.rst

@@ -3,10 +3,10 @@
 Внедрение зависимостей
 =======================
 
-Внедрение зависимостей (Dependency Injection, ``di`` ) — это паттерн проектирования, который помогает писать слабосвязанный, легко тестируемый и расширяемый код. Вместо того чтобы обработчики сами создавали нужные им объекты (зависимости), они получают их извне.
+Внедрение зависимостей (Dependency Injection, DI) — это паттерн проектирования, который помогает писать слабосвязанный, легко тестируемый и расширяемый код. Вместо того чтобы обработчики сами создавали нужные им объекты (зависимости), они получают их извне.
 
-``Argenta`` использует библиотеку ``dishka`` для реализации ``di``, что позволяет декларативно объявлять зависимости прямо в сигнатурах ваших обработчиков.
+``Argenta`` использует библиотеку ``dishka`` для реализации DI, что позволяет декларативно объявлять зависимости прямо в сигнатурах ваших обработчиков.
-Подробнее о **DI**, **IoC** и API для создания провайдеров можно прочитать в `официальной документации dishka <https://dishka.readthedocs.io/en/stable/di_intro.html>`_.
+Подробнее о DI, IoC и API для создания провайдеров можно прочитать в `официальной документации dishka <https://dishka.readthedocs.io/en/stable/di_intro.html>`_.
 
 -----
 
@@ -35,7 +35,7 @@
 После создания провайдера его необходимо зарегистрировать в оркестраторе.
 
 .. note::
-   Провайдеры регистрируются в ``Orchestrator``, а не в ``App``, так как оркестратор отвечает за настройку di-контейнера на уровне всего приложения. Вы можете передать список из нескольких провайдеров через параметр ``custom_providers``.
+   Провайдеры регистрируются в ``Orchestrator``, а не в ``App``, так как оркестратор отвечает за настройку DI-контейнера на уровне всего приложения. Вы можете передать список из нескольких провайдеров через параметр ``custom_providers``.
 
 **Пример использования:**
 
@@ -48,7 +48,7 @@
 Как это работает?
 -----------------
 
-В основе ``di`` в Argenta лежат **провайдеры** и **контейнер**.
+В основе DI в Argenta лежат **провайдеры** и **контейнер**.
 
 *   **Провайдер (Provider)** — это "рецепт", который объясняет, как создавать и настраивать ту или иную зависимость (например, подключение к БД, API-клиент или любой другой сервис).
 *   **Контейнер (IoC Container)** — это "фабрика", которая хранит все рецепты (провайдеры) и по запросу создаёт и выдаёт готовые зависимости.
@@ -71,7 +71,7 @@
 Обмен данными между обработчиками
 ----------------------------------
 
-Помимо ``di``, обработчики могут обмениваться данными в рамках сессии через **объект контекста**. В ``Argenta`` эту роль выполняет объект ``DataBridge``.
+Помимо DI, обработчики могут обмениваться данными в рамках сессии через **объект контекста**. В ``Argenta`` эту роль выполняет объект ``DataBridge``.
 
 Каждый обработчик может записывать в него данные, а также читать, обновлять и удалять их.
 

docs/root/flags.rst

@@ -1,7 +1,7 @@
 .. _root_flags:
 
-Флаги команд
+Флаги вводимых команд
-============
+=====================
 
 Флаги — это специальные параметры, которые пользователь может добавлять к командам для управления их поведением. 
 
@@ -60,9 +60,9 @@
 
 .. code-block:: shell
 
-   greet --name John        # Flag with value
+   greet --name John
-   deploy --verbose         # Flag without value (switch)
+   deploy --verbose
-   backup -f --compress     # Several flags
+   backup -f --compress
 
 -----
 
@@ -91,7 +91,12 @@
 Два типа флагов
 ---------------
 
-Флаги бывают двух основных видов: без значений (переключатели) и со значениями. ``Argenta`` позволяет регистрировать и вводить флаги обоих типов в любой последовательности для одной команды.
+Флаги бывают двух основных видов:
+
+1. **Флаги со значениями** — принимают параметр после имени флага (например, ``--name John``, ``--port 8080``)
+2. **Флаги-переключатели** — не принимают значения, их наличие само по себе является сигналом (например, ``--verbose``, ``--force``)
+
+``Argenta`` позволяет регистрировать и вводить флаги обоих типов в любой последовательности для одной команды.
 
 .. note::
     Ошибки валидации не выбрасывают исключений. Вместо этого у каждого объекта :ref:`InputFlag <root_api_command_input_flag>` есть атрибут ``status``, по которому можно определить, прошла ли валидация успешно. Подробное описание API для создания флагов находится в разделе :ref:`Flag <root_api_command_flag>`.

docs/root/quickstart.rst

@@ -41,25 +41,33 @@
 Промежуточный пример: Калькулятор с флагами
 --------------------------------------------
 
-Прежде чем перейти к сложному примеру с ``di``, рассмотрим промежуточный вариант — калькулятор, который использует флаги для управления поведением.
+Прежде чем перейти к сложному примеру с DI, рассмотрим промежуточный вариант — калькулятор, который использует флаги для управления поведением.
 
 .. literalinclude:: ../code_snippets/quickstart/calculator_app.py
    :language: python
    :linenos:
 
+**Запуск:**
+
+Сохраните код в файл ``calculator.py`` и запустите:
+
+.. code-block:: shell
+
+    python calculator.py
+
 **Использование:**
 
 .. code-block:: shell
 
-   calc --a 10 --b 5 --operation add    # Result: 15.0
+   calc --a 10 --b 5 --operation add
-   calc --a 10 --b 5 --operation mul    # Result: 50.0
+   calc --a 10 --b 5 --operation mul
 
-Этот пример показывает, как работать с флагами без использования ``di``. Теперь перейдём к более сложному примеру.
+Этот пример показывает, как работать с флагами без использования DI. Теперь перейдём к более сложному примеру.
 
 -----
 
-Сложный пример: Менеджер задач с ``di``
+Сложный пример: Менеджер задач с DI
---------------------------------------
+------------------------------------
 
 В этом руководстве мы создадим полнофункциональное CLI-приложение «Менеджер задач», которое продемонстрирует работу с внедрением зависимостей.