docs: добавь поясняющие комментарии к модулям и инструментам

python/set_devices/qt_ports/__init__.py

@@ -1 +1,5 @@
+# Входная точка пакета set_devices.qt_ports. Определяет доступные при импорте имена; подробные
+# контракты находятся в специализированных модулях пакета. Изменение реэкспортов влияет на
+# существующие import у потребителей.
+
 """Reusable device libraries from setcorp/templates."""

python/set_devices/qt_ports/candle_adapter.py

@@ -1,3 +1,7 @@
+# Qt-совместимый транспорт WinUSB для candleLight/gs_usb. Детали ctypes скрыты в адаптере;
+# жизненный цикл устройства и канала должен завершаться закрытием ресурсов независимо от
+# состояния интерфейса.
+
 """WinUSB transport for candleLight/gs_usb CAN adapters.
 
 The native library is the same Candle API used by CANgaroo.  This module keeps

python/set_devices/qt_ports/f407_usb_bootloader.py

@@ -1,3 +1,7 @@
+# Асинхронный обновитель односекционного STM32F407 через SET v2 USB. Проверка образа
+# предшествует передаче, а продвижение по этапам зависит от ответов загрузчика; интерфейс не
+# должен блокироваться ожиданием Flash.
+
 """Asynchronous SET v2 USB updater for the STM32F407VE single-slot port."""
 from __future__ import annotations
 import struct

python/set_devices/qt_ports/mock_port.py

@@ -1,3 +1,7 @@
+# Qt-порт виртуального устройства для разработки интерфейса без COM-подключения. Сигналы и
+# ответы повторяют контракт обычного порта, чтобы UI мог переключать источник без изменения
+# обработчиков.
+
 """@file mock_port.py
 @brief Qt-таймер, имитирующий подключённый контроллер без COM-порта.
 

python/set_devices/qt_ports/plot_annotations.py

@@ -1,3 +1,7 @@
+# Отрисовка математических подписей кривых средствами Qt. Выравнивание и координаты текста
+# относятся к представлению; сами коэффициенты и данные реконструкции должны приходить из
+# модели расчёта.
+
 """Small right-aligned mathematical annotations shared by Qt plots."""
 try:
     from PySide6.QtCore import QRectF, Qt

python/set_devices/qt_ports/plot_navigation.py

@@ -1,3 +1,7 @@
+# Общие жесты клавиатуры и колеса для Qt-графиков. Обработчики переводят пользовательские
+# события в изменения области просмотра; настройки осей и сохранение данных остаются в
+# владельце графика.
+
 """Common keyboard and wheel gestures for all plot canvases (Qt 5/6)."""
 try:
     from PySide6.QtCore import Qt

python/set_devices/qt_ports/plot_processing.py

@@ -1,3 +1,7 @@
+# Qt-панель обработки графиков с выполнением расчётов в рабочей задаче. Снимок входных данных
+# отделён от живого графика; сигналы доставляют результат обратно в UI для добавления
+# самостоятельной вычисленной кривой.
+
 """Reusable Qt processing panel and plot attachment; no SETGUI dependency."""
 from __future__ import annotations
 from dataclasses import replace

python/set_devices/qt_ports/port_selection.py

@@ -1,3 +1,6 @@
+# Единое отображение и выбор последовательного порта в Qt-интерфейсе. Пользовательская подпись
+# может содержать описание устройства, но для открытия сохраняется системное имя порта.
+
 """Shared serial-port labels and selection for Qt project interfaces."""
 
 

python/set_devices/qt_ports/qt_compat.py

@@ -1,3 +1,7 @@
+# Точка импорта зависимостей Qt для транспортных адаптеров. Базовый пакет устройств не должен
+# загружать Qt при обычном импорте: это позволяет использовать переносимые модели в консольных
+# инструментах.
+
 """Qt transport dependencies; importing set_devices itself never loads Qt."""
 try:
     from PySide6.QtCore import QObject, Signal, QTimer, QElapsedTimer

python/set_devices/qt_ports/serial_port.py

@@ -1,3 +1,7 @@
+# Асинхронный QSerialPort с передачей входных фрагментов потоковому parser. Сигнал readyRead
+# не гарантирует целый кадр; открытие, закрытие и ошибки соединения обслуживаются в жизненном
+# цикле Qt.
+
 """@file serial_port.py
 @brief Неблокирующий QSerialPort и потоковый parser GUI transport.
 

python/set_devices/qt_ports/slcan_adapter.py

@@ -1,3 +1,7 @@
+# Последовательный транспорт Lawicel/SLCAN для CAN-адаптера. Текстовое представление кодирует
+# ID, длину и данные кадра; окончания строк разделяют команды и требуют накопления неполной
+# строки.
+
 """Serial Line CAN (Lawicel/SLCAN) transport."""
 
 from __future__ import annotations

python/set_devices/qt_ports/stm32_bootloader.py

@@ -1,3 +1,6 @@
+# Неблокирующий клиент ROM UART-загрузчика STM32. Команды и ACK/NACK обслуживаются
+# последовательными состояниями, чтобы ожидание устройства не блокировало цикл Qt.
+
 """Non-blocking client for the STM32 ROM UART bootloader described by AN3155."""
 
 from __future__ import annotations

python/set_devices/qt_ports/stm_settings.py

@@ -1,3 +1,7 @@
+# Транзакционное изменение настроек STM через регистровые команды FC03/FC06. Чтение, проверка
+# ответа и подтверждение записи составляют один клиентский обмен; отправка запроса не равна
+# успешному применению.
+
 """Transactional STM configuration extension (FC03/FC06, 0x1210)."""
 import struct
 

python/set_devices/qt_ports/tms_bootloader.py

@@ -1,3 +1,6 @@
+# Неблокирующая последовательность INITLOAD/LOAD/TFLASH для TMS. Ответы и таймауты управляют
+# переходами между этапами; размеры блоков и адреса берутся из протокола целевого контроллера.
+
 """Non-blocking port of Gui_Android's INITLOAD / LOAD / TFLASH workflow."""
 from .qt_compat import QObject, QTimer, Signal
 from .qt_compat import QSerialPort

python/set_devices/qt_ports/ump_can_client.py

@@ -1,3 +1,6 @@
+# Асинхронный клиент CAN-запросов УМП поверх существующего соединения. Ожидаемый ответ
+# привязан к активному запросу; транспортный цикл Qt отделён от модели регистратора.
+
 """Последовательный клиент CAN-логгера поверх уже подключённого Dima-адаптера."""
 import secrets
 from .qt_compat import QObject, QTimer, Signal

python/set_devices/qt_ports/wavegen.py

@@ -1,3 +1,7 @@
+# Рабочий транспорт генератора по USB CDC/COM для WG и блочной загрузки SET v2. Ожидания
+# выполняются в рабочем потоке; результаты возвращаются через сигналы, сохраняя отзывчивость
+# интерфейса.
+
 """USB CDC/COM worker for WG v1/v2/v3, with SET v2 block uploads. All waits run in a worker, never the GUI thread."""
 import time
 from PySide6.QtCore import QObject, QRunnable, Signal, QIODevice