docs

docs/root/api/command/index.rst

@@ -3,14 +3,145 @@
 Command
 =======
 
-.. toctree::
-    :hidden:
+Объект ``Command`` представляет собой основную единицу функциональности в приложении ``Argenta``. Каждая команда определяет конкретное действие, которое пользователь может выполнить, введя соответствующий триггер. Команды регистрируются в роутерах и образуют интерфейс взаимодействия с приложением.
+
+``Command`` инкапсулирует всю необходимую информацию о команде: её триггер (ключевое слово для вызова), описание, набор флагов для настройки поведения и список псевдонимов для альтернативных способов вызова.
+
+-----
+
+Инициализация
+-------------
+
+.. code-block:: python
+   :linenos:
+
+   __init__(self, trigger: str, *,
+            description: str | None = None,
+            flags: Flag | Flags = DEFAULT_WITHOUT_FLAGS,
+            aliases: list[str] | None = None) -> None
+
+Создает новую команду для регистрации в роутере.
+
+* ``trigger`` : Строковый триггер команды, который пользователь должен ввести для её вызова. Это основной идентификатор команды в системе.
+
+* ``description`` : Необязательное описание команды, объясняющее её назначение. Если не указано, используется значение по умолчанию ``"Command without description"``. Отображается в справке и списке доступных команд.
+
+* ``flags`` : Набор флагов команды для настройки её поведения. Может быть одиночным объектом ``Flag`` или коллекцией ``Flags``. По умолчанию команда создается без флагов.
+
+* ``aliases`` : Список строковых синонимов для основного триггера. Позволяет вызывать команду альтернативными способами. По умолчанию список пуст.
+
+**Атрибуты:**
+
+.. py:attribute:: trigger
+
+   Основной триггер команды в виде строки. Используется для идентификации команды при парсинге пользовательского ввода.
+
+.. py:attribute:: description
+
+   Текстовое описание команды. Если не было передано при инициализации, содержит значение ``"Command without description"``.
+
+.. py:attribute:: registered_flags
+
+   Объект ``Flags``, содержащий все зарегистрированные флаги команды. Автоматически конвертируется из одиночного ``Flag`` в коллекцию при инициализации.
+
+.. py:attribute:: aliases
+
+   Список строк с альтернативными триггерами команды. Пустой список, если псевдонимы не заданы.
+
+**Пример использования:**
+
+.. literalinclude:: ../../../code_snippets/command_snippet.py
+   :linenos:
+   
+.. seealso ::
+   Подробнее про флаги: :ref:`Flags <root_api_command_flags>` и :ref:`Флаги вводимых команд <root_flags>`.
+
+-----
+
+Регистрация команд
+------------------
+
+Команды регистрируются в роутерах с помощью декоратора ``@router.command()``. После регистрации команда становится доступной пользователям для вызова.
+
+**Базовый пример:**
+
+.. literalinclude:: ../../../code_snippets/command_snippet2.py
+   :linenos:
+
+**Команды с флагами:**
+
+.. literalinclude:: ../../../code_snippets/command_snippet3.py
+   :linenos:
+
+-----
+
+Работа с псевдонимами
+---------------------
+
+Псевдонимы позволяют вызывать один и тот же хэндлер разными триггерами, сохраняя при этом флаги команды и описание.
+
+**Пример с псевдонимами:**
+
+.. code-block:: python
+   :linenos:
+
+   from argenta import Router, Command
+
+   router = Router(title="System")
+
+   @router.command(Command(
+       "shutdown",
+       description="Shutdown the system",
+       aliases=["poweroff", "halt", "stop"]
+   ))
+   def handle_shutdown(response):
+       response.write("Shutting down the system...")
+
+Теперь пользователь может вызвать команду любым из способов:
+
+.. code-block:: bash
+
+   shutdown
+   poweroff
+   halt
+   stop
+
+Все эти варианты выполнят одну и ту же функцию ``handle_shutdown``.
+
+-----
     
-    flags
-    possible_values
-    validation_status
-    
-.. _input_command:
+.. _root_api_command_input_command:
 
 InputCommand
-~~~~~~~~~~~~
+------------
+
+Класс ``InputCommand`` представляет собой распаршенную команду, введенную пользователем. Это внутренний класс, который создается автоматически при парсинге пользовательского ввода. Непосредственная работа с данным классом возможна при создании кастомного хэндлера для обработки неизвестных команд.
+
+.. seealso ::
+   Подробнее про кастомные хэндлеры обработки исключений ввода :ref:`тут <root_error_handling>`
+
+Создает экземпляр распарсенной команды.
+
+:param trigger: Триггер команды, извлеченный из пользовательского ввода
+:param input_flags: Флаги, переданные пользователем при вызове команды
+
+**Атрибуты:**
+
+.. py:attribute:: trigger
+   :no-index:
+
+   Строковый триггер команды, введенный пользователем.
+
+.. py:attribute:: input_flags
+
+   Объект ``InputFlags``, содержащий все флаги, переданные с командой. Автоматически конвертируется из одиночного ``InputFlag`` в коллекцию.
+
+.. toctree ::
+    :hidden:
+    
+    flag
+    possible_values
+    input_flag
+    validation_status
+    flags 
+    input_flags