update docs

docs/root/api/command/input_flag.rst

@@ -9,7 +9,7 @@ InputFlag
 
    Документация по :ref:`Flag <root_api_command_flag>` — сущность флага, регистрируемого для последующей обработки.
 
-   Документация по :ref:`ValidationStatus <root_api_validation_status>` — статусы валидации флагов.
+   Документация по :ref:`ValidationStatus <root_api_command_validation_status>` — статусы валидации флагов.
 
 -----
 
@@ -33,6 +33,9 @@ InputFlag
 * ``input_value`` : Значение введённого флага. Может быть ``None`` если флаг не принимает значения
 * ``status`` : Статус валидации флага из перечисления ``ValidationStatus``
 
+.. warning ::
+   Экземпляры класса не предназначены для их прямого создания, они содержаться в контейнере :ref:`Response <root_api_response>`
+
 **Атрибуты:**
 
 .. py:attribute:: name

docs/root/api/command/validation_status.rst

@@ -1,6 +1,109 @@
 .. _root_api_command_validation_status:
 
 ValidationStatus
-****************
+================
+
+Enum ``ValidationStatus`` представляет собой перечисление, определяющее состояние валидации значений флагов в приложении ``Argenta``. Его основная задача — предоставить стандартизированные константы для отображения результата проверки введённых пользователем флагов и их значений. ``ValidationStatus`` используется в атрибуте ``status`` класса ``InputFlag`` для информирования о том, прошёл ли флаг валидацию успешно.
+
+``ValidationStatus`` наследуется от стандартного класса ``Enum`` и содержит три основных значения: ``VALID`` для корректных флагов, ``INVALID`` для некорректных флагов и ``UNDEFINED`` для незарегистрированных флагов.
+
+.. note::
+
+   Статус валидации устанавливается автоматически при создании экземпляра ``InputFlag`` на основе проверки через соответствующий ``Flag``.
+
+.. seealso::
+
+   Документация по :ref:`InputFlag <root_api_command_input_flag>` — сущности входного флага, использующей ``ValidationStatus``
+   
+   Документация по :ref:`Flag <root_api_command_flag>` — сущности флага с методом валидации
+   
+   Документация по :ref:`PossibleValues <root_api_command_possible_values>` — типам допустимых значений флагов
+
+-----
+
+Значения enum
+-------------
+
+VALID
+~~~~~
+
+.. code-block:: python
+   :linenos:
+
+   ValidationStatus.VALID = 'VALID'
+
+Указывает, что флаг и его значение **прошли** валидацию успешно.
+
+Флаги с этим статусом полностью соответствуют правилам, заданным в параметре ``possible_values`` соответствующего ``Flag``. Такие флаги могут быть безопасно использованы в логике приложения без дополнительных проверок.
+
+**Условия получения статуса** ``VALID``:
+
+* Флаг с ``PossibleValues.NEITHER`` передан без значения
+* Флаг с ``PossibleValues.ALL`` передан с любым значением или без него
+* Флаг со списком значений передан с одним из допустимых значений
+* Флаг с регулярным выражением передан со значением, соответствующим паттерну
+
+**Пример использования:**
+
+.. literalinclude:: ../../../code_snippets/validation_status_valid_snippet1.py
+   :linenos:
+   :language: python
+
+-----
+
+INVALID
+~~~~~~~
+
+.. code-block:: python
+   :linenos:
+
+   ValidationStatus.INVALID = 'INVALID'
+
+Указывает, что флаг или его значение **не прошли** валидацию.
+
+Флаги с этим статусом нарушают правила, установленные в ``possible_values`` соответствующего ``Flag``. Такие флаги должны быть обработаны как ошибочные, и их использование может привести к некорректной работе приложения.
+
+**Условия получения статуса** ``INVALID``:
+
+* Флаг с ``PossibleValues.NEITHER`` передан со значением
+* Флаг со списком значений передан с недопустимым значением
+* Флаг с регулярным выражением передан со значением, не соответствующим паттерну
+* Флаг требует значение, но передан без него (для определённых типов валидации)
+
+**Пример использования:**
+
+.. literalinclude:: ../../../code_snippets/validation_status_invalid_snippet2.py
+   :linenos:
+   :language: python
+
+-----
+
+UNDEFINED
+~~~~~~~~~
+
+.. code-block:: python
+   :linenos:
+
+   ValidationStatus.UNDEFINED = 'UNDEFINED'
+
+Указывает, что флаг был введён, но не зарегистрирован.
+
+**Условия получения статуса** ``UNDEFINED``:
+
+* Флаг был введён с любым значением, но не зарегистрирован
+
+-----
+
+
+Практические примеры
+--------------------
+
+Комплексный пример валидации
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Пример демонстрирует использование всех статусов в реальном сценарии:
+
+.. literalinclude:: ../../../code_snippets/validation_status_comprehensive_snippet6.py
+   :linenos:
+   :language: python
 
-case