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

c/gas-logger/CMakeLists.txt

@@ -1,3 +1,7 @@
+# Сборка библиотеки gas_logger, gas_logger_pm35, gas_logger_pcan. Состав исходников и
+# публичные include-пути задают подключение к проекту потребителя. Файл также собирает и
+# регистрирует хостовые проверки; запускать их следует через CTest из каталога сборки.
+
 cmake_minimum_required(VERSION 3.16)
 project(gas_logger C)
 set(CMAKE_C_STANDARD 99)

c/gas-logger/include/gas_logger.h

@@ -1,3 +1,9 @@
+/*
+ * Непрерывная запись каналов в два банка и выдача согласованного снимка через регистровый
+ * интерфейс. Адреса и количества регистратора считаются в 16-битных словах, включая C28x;
+ * чтение снимка отделено от текущего сбора.
+ */
+
 /* Portable continuous recorder. All addresses/counts are 16-bit WORDS,
  * including on C28x (CHAR_BIT=16). No heap, UART, HAL or global state. */
 #ifndef GAS_LOGGER_H

c/gas-logger/include/gas_logger_pcan.h

@@ -1,3 +1,9 @@
+/*
+ * Подключение регистратора к диспетчеру ProtoCAN GAS. Адаптер переводит относительное смещение
+ * региона в адрес регистратора и сопоставляет коды ошибок двух интерфейсов, сохраняя сам сбор
+ * данных в gas_logger.
+ */
+
 #ifndef GAS_LOGGER_PCAN_H
 #define GAS_LOGGER_PCAN_H
 #include "gas_logger.h"

c/gas-logger/ports/c28x/gas_logger_c28x.c

@@ -1,3 +1,9 @@
+/*
+ * Критические секции регистратора для TI C28x. При входе сохраняется прежнее состояние
+ * прерываний, при выходе восстанавливается именно оно: безусловное разрешение нарушило бы
+ * вложенную критическую секцию.
+ */
+
 #include "gas_logger_c28x.h"
 /* __disable_interrupts/__restore_interrupts are TI C28x compiler intrinsics. */
 uint32_t gl_c28x_enter(void *user) { (void)user; return __disable_interrupts(); }

c/gas-logger/ports/c28x/gas_logger_c28x.h

@@ -1,3 +1,9 @@
+/*
+ * Критические секции регистратора для TI C28x. При входе сохраняется прежнее состояние
+ * прерываний, при выходе восстанавливается именно оно: безусловное разрешение нарушило бы
+ * вложенную критическую секцию.
+ */
+
 #ifndef GAS_LOGGER_C28X_H
 #define GAS_LOGGER_C28X_H
 #include <stdint.h>

c/gas-logger/ports/pm35/gas_logger_pm35.c

@@ -1,3 +1,9 @@
+/*
+ * Связь регистратора ПМ35 с картой доступных сигналов. Адреса сигналов согласуются с
+ * JSON-картой клиента; изменение только одной стороны приводит к неверной интерпретации снимка
+ * даже при успешном обмене.
+ */
+
 #include "gas_logger_pm35.h"
 #include "pm35_map.h"
 static uint32_t enter(void *u) { gl_pm35_context *p=u; return p->enter(p->irq_user); }

c/gas-logger/ports/pm35/gas_logger_pm35.h

@@ -1,3 +1,9 @@
+/*
+ * Связь регистратора ПМ35 с картой доступных сигналов. Адреса сигналов согласуются с
+ * JSON-картой клиента; изменение только одной стороны приводит к неверной интерпретации снимка
+ * даже при успешном обмене.
+ */
+
 #ifndef GAS_LOGGER_PM35_H
 #define GAS_LOGGER_PM35_H
 #include "gas_logger.h"

c/gas-logger/ports/pm35/pm35_map.h

@@ -1,3 +1,9 @@
+/*
+ * Связь регистратора ПМ35 с картой доступных сигналов. Адреса сигналов согласуются с
+ * JSON-картой клиента; изменение только одной стороны приводит к неверной интерпретации снимка
+ * даже при успешном обмене.
+ */
+
 /* Generated from pm35.json. Do not edit. */
 #ifndef GL_PM35_MAP_H
 #define GL_PM35_MAP_H

c/gas-logger/ports/stm32/gas_logger_stm32.c

@@ -1,3 +1,9 @@
+/*
+ * Критические секции регистратора для STM32 через состояние маски прерываний. Сохранённое
+ * значение передаётся из входа в выход, чтобы не разрешить прерывания, уже запрещённые
+ * вызывающим кодом.
+ */
+
 #include "gas_logger_stm32.h"
 #ifndef GL_STM32_DEVICE_HEADER
 #define GL_STM32_DEVICE_HEADER "stm32f4xx.h"

c/gas-logger/ports/stm32/gas_logger_stm32.h

@@ -1,3 +1,9 @@
+/*
+ * Критические секции регистратора для STM32 через состояние маски прерываний. Сохранённое
+ * значение передаётся из входа в выход, чтобы не разрешить прерывания, уже запрещённые
+ * вызывающим кодом.
+ */
+
 #ifndef GAS_LOGGER_STM32_H
 #define GAS_LOGGER_STM32_H
 #include <stdint.h>

c/gas-logger/src/gas_logger.c

@@ -1,3 +1,9 @@
+/*
+ * Непрерывная запись каналов в два банка и выдача согласованного снимка через регистровый
+ * интерфейс. Адреса и количества регистратора считаются в 16-битных словах, включая C28x;
+ * чтение снимка отделено от текущего сбора.
+ */
+
 #include "gas_logger.h"
 #include <stddef.h>
 #include <string.h>

c/gas-logger/src/gas_logger_pcan.c

@@ -1,3 +1,9 @@
+/*
+ * Подключение регистратора к диспетчеру ProtoCAN GAS. Адаптер переводит относительное смещение
+ * региона в адрес регистратора и сопоставляет коды ошибок двух интерфейсов, сохраняя сам сбор
+ * данных в gas_logger.
+ */
+
 #include "gas_logger_pcan.h"
 static pcan_gas_status_t result(gl_result r)
 { return r==GL_OK ? PCAN_GAS_OK : r==GL_ADDRESS ? PCAN_GAS_NO_REG : PCAN_GAS_REJECTED; }

c/gas-logger/tests/host_device.c

@@ -1,3 +1,9 @@
+/*
+ * Проверки host_device: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 /* Host-only firmware harness for the actual PM35 port and Python client. */
 #include "gas_logger_pm35.h"
 #include "gas_logger_pcan.h"

c/gas-logger/tests/run_tests.py

@@ -1,3 +1,7 @@
+# Проверки run_tests: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 """Build in a temporary directory; run core + Python/C end-to-end tests."""
 import argparse
 import ctypes

c/gas-logger/tests/test_client.py

@@ -1,3 +1,17 @@
+# Проверки client: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_download_keeps_recording_and_order
+#   test_cancel_retains_snapshot_and_explicit_resume
+#   test_partial_reply_leaves_pin
+#   test_no_writes_for_wrong_schema
+#   test_generation_mismatch_does_not_release
+#   test_classic_can_chunks_and_pcan_region
+#   test_json_rejects_collisions_and_drift
+#   test_replaced_snapshot_is_rejected_before_release
+# Остальные сценарии продолжают эти проверки ниже в том же файле.
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 """Integration: Python client -> register callbacks -> compiled C PM35 logger."""
 import copy
 import ctypes

c/gas-logger/tests/test_gas_logger.c

@@ -1,3 +1,9 @@
+/*
+ * Проверки gas_logger: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 #include "gas_logger.h"
 #include <assert.h>
 #include <stdio.h>

c/gas-logger/tools/generate_map.py

@@ -1,3 +1,7 @@
+# Генерация C-представления карты сигналов из JSON и проверка его актуальности. Один источник
+# карты связывает прошивку и клиента; ручная правка сгенерированной таблицы создаст
+# расхождение при следующей генерации.
+
 """Regenerate/verify the firmware mirror of the packaged JSON map."""
 from pathlib import Path
 import argparse