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

python/setprotocol/__init__.py

@@ -1,3 +1,7 @@
+# Входная точка пакета setprotocol. Определяет доступные при импорте имена; подробные
+# контракты находятся в специализированных модулях пакета. Изменение реэкспортов влияет на
+# существующие import у потребителей.
+
 """Cross-platform Python facade for the canonical SETProtocol core."""
 
 from .core import *  # noqa: F401,F403

python/setprotocol/can.py

@@ -1,3 +1,7 @@
+# Сегментация кадров SETProtocol v2 в classic CAN: первый пакет несёт длину и пять байт
+# данных, последующие — номер и до семи байт. Сборщик обслуживает один источник и канал;
+# таймаут или нарушение последовательности сбрасывает неполный кадр.
+
 """Classic-CAN segmentation for canonical SETProtocol v2 frames."""
 
 from __future__ import annotations
@@ -90,6 +94,8 @@ def segment(packet: bytes, address: CanAddress) -> list[CanFrame]:
             + packet[:FIRST_DATA_SIZE],
         )
     ]
+    # Номер занимает младшую тетраду PCI и циклически переходит 15 -> 0.
+    # Он проверяет порядок фрагментов, но не является полным номером блока.
     sequence = 1
     for offset in range(FIRST_DATA_SIZE, len(packet), CONSECUTIVE_DATA_SIZE):
         chunk = packet[offset : offset + CONSECUTIVE_DATA_SIZE]
@@ -115,6 +121,8 @@ class CanReassembler:
         self._next_sequence = 1
 
     def feed(self, frame: CanFrame, now_ms: int) -> bytes | None:
+        # now_ms должен поступать из одной монотонной шкалы времени клиента.
+        # Таймаут относится к интервалу между принятыми сегментами.
         if self._can_id is not None and now_ms >= self._deadline_ms:
             self.reset()
             raise SetProtocolError("таймаут сборки SETProtocol CAN")
@@ -125,6 +133,8 @@ class CanReassembler:
             total = int.from_bytes(frame.data[1:3], "little")
             if not HEADER_SIZE + CRC_SIZE <= total <= FRAME_MAX:
                 raise SetProtocolError("неверная полная длина SETP CAN")
+            # FIRST начинает новую сборку, заменяя ранее накопленный хвост.
+            # Сохраняем полный CAN ID, чтобы не смешать источники и каналы.
             self._buffer = bytearray(frame.data[3:])
             self._expected_length = total
             self._can_id = frame.can_id
@@ -151,6 +161,8 @@ class CanReassembler:
             self._deadline_ms = now_ms + self.timeout_ms
             if len(self._buffer) != self._expected_length:
                 return None
+            # Создаём независимый неизменяемый результат до сброса контекста.
+            # Проверка согласованности адресов ниже уже не удерживает сборку.
             packet = bytes(self._buffer)
             can_id = self._can_id
             self.reset()
@@ -167,6 +179,8 @@ class CanReassembler:
                 or priority != address.priority
             ):
                 raise SetProtocolError("SETP header не совпадает с CAN ID")
+            # Здесь проверена транспортная сборка. CRC самого SET-кадра
+            # проверяет следующий слой декодирования протокола.
             return packet
         if pci == PCI_FLOW_CONTROL:
             return None

python/setprotocol/core.py

@@ -1,3 +1,7 @@
+# Основной бинарный формат SETProtocol v2: поля кадра, контрольная сумма и потоковый parser.
+# Числа сериализуются явно, поэтому выравнивание C-структур не влияет на байты линии;
+# транспорт передаёт готовые массивы.
+
 """Эталонная Python-реализация SET protocol v2.
 
 Источник wire-контракта находится в ``templates/c/set-protocol/PROTOCOL.md``.

python/setprotocol/firmware_catalog.py

@@ -1,3 +1,7 @@
+# Модель каталога firmware.releases и проверка записей update.json. Метаданные выпуска
+# описывают совместимость и расположение образа; выбор записи и последующее скачивание
+# являются отдельными операциями.
+
 """Shared firmware release catalog contract from ``update.json``."""
 
 from __future__ import annotations

python/setprotocol/firmware_database.py

@@ -1,3 +1,7 @@
+# Самостоятельный доступ к базе прошивок: HTTPS, проверяемая загрузка, кэш и публикация в
+# Gitea. Проверка SHA-256 связывает скачанные байты с записью каталога; сетевые полномочия
+# передаются явно через клиент.
+
 """Standalone firmware database: HTTPS catalog, verified downloads and Gitea publishing.
 
 No Qt, desktop application, credential store or MCU dependencies.

python/setprotocol/firmware_publish.py

@@ -1,3 +1,7 @@
+# Общие правила метаданных публикации прошивки: SHA-256, release tag и обновление каталога.
+# Формирование записи отделено от сетевой загрузки; идентичность выпуска нужна для
+# предсказуемой замены существующей записи.
+
 """Reusable helpers for publishing the shared firmware release catalog."""
 
 from __future__ import annotations