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

c/can-sensor/CMakeLists.txt

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

c/can-sensor/can_sensor.c

@@ -1,3 +1,9 @@
+/*
+ * Обмен настройками датчиков DS18B20 через однокадровые сообщения SETCAN. ROM идентифицирует
+ * датчик независимо от его позиции; прикладное состояние и отправка CAN предоставляются через
+ * интерфейс библиотеки.
+ */
+
 /**
  * @file can_sensor.c
  * @brief Однокадровый транспорт SETCAN SETTINGS для локаций DS18B20.

c/can-sensor/can_sensor.h

@@ -1,3 +1,9 @@
+/*
+ * Обмен настройками датчиков DS18B20 через однокадровые сообщения SETCAN. ROM идентифицирует
+ * датчик независимо от его позиции; прикладное состояние и отправка CAN предоставляются через
+ * интерфейс библиотеки.
+ */
+
 /**
  * @file can_sensor.h
  * @brief Портируемый транспорт SETTINGS для привязки DS18B20 к локации.

c/can-sensor/ports/stm32f1/can_sensor_stm32f1.c

@@ -1,3 +1,9 @@
+/*
+ * Прямой bxCAN-порт датчиков для STM32F1 без HAL. Регистры контроллера обеспечивают передачу и
+ * приём SETCAN, а конфигурация платы задаёт подключение шины; это аппаратная реализация
+ * интерфейса can_sensor.
+ */
+
 /**
  * @file can_sensor_stm32f1.c
  * @brief Опросный порт can-sensor на bxCAN STM32F1 без STM32 HAL.

c/can-sensor/ports/stm32f1/can_sensor_stm32f1.h

@@ -1,3 +1,9 @@
+/*
+ * Прямой bxCAN-порт датчиков для STM32F1 без HAL. Регистры контроллера обеспечивают передачу и
+ * приём SETCAN, а конфигурация платы задаёт подключение шины; это аппаратная реализация
+ * интерфейса can_sensor.
+ */
+
 /**
  * @file can_sensor_stm32f1.h
  * @brief Опросный порт can-sensor на bxCAN микроконтроллеров STM32F1.

c/can-sensor/ports/stm32f1/can_sensor_stm32f1_config.f103.template.h

@@ -1,3 +1,9 @@
+/*
+ * Конфигурация can-sensor для порта stm32f1. Макросы задают параметры сборки и ограничения,
+ * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров
+ * памяти и параметров устройства необходимо согласовать с целевой платой.
+ */
+
 /**
  * @file can_sensor_stm32f1_config.f103.template.h
  * @brief Шаблон выводов CAN1 для STM32F103 без ремапа.

c/can-sensor/tests/test_can_sensor.c

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

c/candle/CMakeLists.txt

@@ -1,3 +1,7 @@
+# Сборка библиотеки candle. Состав исходников и публичные include-пути задают подключение к
+# проекту потребителя. Платформенные зависимости и условия сборки задаются здесь, а не в
+# прикладных исходниках.
+
 cmake_minimum_required(VERSION 3.15)
 project(candle C)
 if(NOT WIN32)

c/candle/candle.c

@@ -19,6 +19,12 @@
 
 */
 
+/*
+ * Доступ к CAN-адаптерам candleLight/gs_usb в Windows через WinUSB. Перечисление устройств,
+ * открытие канала и обмен кадрами образуют отдельный транспортный слой; он не интерпретирует
+ * прикладные регистры SETProtocol.
+ */
+
 #include "candle.h"
 
 #include <stdarg.h>

c/candle/candle.def

@@ -1,3 +1,7 @@
+; Доступ к CAN-адаптерам candleLight/gs_usb в Windows через WinUSB. Перечисление устройств,
+; открытие канала и обмен кадрами образуют отдельный транспортный слой; он не интерпретирует
+; прикладные регистры SETProtocol.
+
 EXPORTS
     candle_list_scan
     candle_list_free

c/candle/candle.h

@@ -20,6 +20,12 @@
 
 */
 
+/*
+ * Доступ к CAN-адаптерам candleLight/gs_usb в Windows через WinUSB. Перечисление устройств,
+ * открытие канала и обмен кадрами образуют отдельный транспортный слой; он не интерпретирует
+ * прикладные регистры SETProtocol.
+ */
+
 #pragma once
 #include <stdint.h>
 #include <stdbool.h>

c/candle/candle_ctrl_req.c

@@ -19,6 +19,11 @@
 
 */
 
+/*
+ * Управляющие USB-запросы адаптера candleLight: конфигурация, временные параметры CAN и режим
+ * канала. Эти транзакции идут через control endpoint и отличаются от потока CAN-кадров.
+ */
+
 #include "candle_ctrl_req.h"
 #include "ch_9.h"
 

c/candle/candle_ctrl_req.h

@@ -20,6 +20,11 @@
 
 */
 
+/*
+ * Управляющие USB-запросы адаптера candleLight: конфигурация, временные параметры CAN и режим
+ * канала. Эти транзакции идут через control endpoint и отличаются от потока CAN-кадров.
+ */
+
 #pragma once
 
 #include "candle_defs.h"

c/candle/candle_defs.h

@@ -20,6 +20,12 @@
 
 */
 
+/*
+ * Двоичные структуры и константы gs_usb, общие для драйвера и USB-адаптера. Размеры полей и
+ * упаковка определяют совместимость с прошивкой: менять их как обычные внутренние структуры
+ * нельзя.
+ */
+
 #pragma once
 
 #include <stdint.h>

c/candle/ch_9.h

@@ -19,6 +19,11 @@
 
 */
 
+/*
+ * Типы стандартных USB-дескрипторов и запросов из главы 9 спецификации USB. Драйвер использует
+ * их для описания устройства и конечных точек; это транспортные определения, а не формат CAN.
+ */
+
 #pragma once
 
 #define USB_DIR_OUT                     0               /* to device */

c/ds18b20-ds2480/CMakeLists.txt

@@ -1,3 +1,7 @@
+# Сборка библиотеки ds18b20_ds2480. Состав исходников и публичные include-пути задают
+# подключение к проекту потребителя. Файл также собирает и регистрирует хостовые проверки;
+# запускать их следует через CTest из каталога сборки.
+
 cmake_minimum_required(VERSION 3.13)
 project(ds18b20_ds2480 C)
 add_library(ds18b20_ds2480 STATIC ds2480.c ds18b20_ds2480.c)

c/ds18b20-ds2480/ds18b20_ds2480.c

@@ -1,3 +1,9 @@
+/*
+ * Команды DS18B20 поверх интерфейса DS2480B: адресация ROM, преобразование температуры и
+ * scratchpad. Транспортный статус следует проверять до использования результата; сырая
+ * температура сохраняет знаковое представление датчика.
+ */
+
 #include "ds18b20_ds2480.h"
 #include <string.h>
 

c/ds18b20-ds2480/ds18b20_ds2480.h

@@ -1,3 +1,9 @@
+/*
+ * Команды DS18B20 поверх интерфейса DS2480B: адресация ROM, преобразование температуры и
+ * scratchpad. Транспортный статус следует проверять до использования результата; сырая
+ * температура сохраняет знаковое представление датчика.
+ */
+
 #ifndef DS18B20_DS2480_H
 #define DS18B20_DS2480_H
 #include "ds2480.h"

c/ds18b20-ds2480/ds2480.c

@@ -1,3 +1,9 @@
+/*
+ * UART-мост DS2480B для операций 1-Wire: сброс, обмен битами и байтами, поиск устройств и
+ * управление питанием. После ошибки связи состояние готовности сбрасывается, чтобы следующий
+ * обмен не продолжался в неизвестном режиме моста.
+ */
+
 #include "ds2480.h"
 
 static ds2480_status fault(ds2480 *bus, ds2480_status status)

c/ds18b20-ds2480/ds2480.h

@@ -1,3 +1,9 @@
+/*
+ * UART-мост DS2480B для операций 1-Wire: сброс, обмен битами и байтами, поиск устройств и
+ * управление питанием. После ошибки связи состояние готовности сбрасывается, чтобы следующий
+ * обмен не продолжался в неизвестном режиме моста.
+ */
+
 #ifndef DS2480_H
 #define DS2480_H
 

c/ds18b20-ds2480/examples/read_first.c

@@ -1,3 +1,9 @@
+/*
+ * Минимальный блокирующий пример: подготовить мост DS2480B, найти первый датчик, запустить
+ * преобразование и прочитать температуру. Обратные вызовы UART и задержек предоставляет плата;
+ * ожидание преобразования входит во время вызова.
+ */
+
 #include "ds18b20_ds2480.h"
 
 /* board_port supplies the four callbacks documented in ds2480.h.

c/ds18b20-ds2480/ports/stm32f4/ds2480_stm32f4_hal.c

@@ -1,3 +1,9 @@
+/*
+ * UART-порт DS2480B для STM32F4. Подготовка линии и очистка ошибок USART отделены от команд
+ * датчика; после сбоя обмена мост должен пройти предусмотренное восстановление до продолжения
+ * работы с 1-Wire.
+ */
+
 #include "ds2480_stm32f4_hal.h"
 
 #define RX_ERRORS (USART_SR_ORE | USART_SR_NE | USART_SR_FE | USART_SR_PE)

c/ds18b20-ds2480/ports/stm32f4/ds2480_stm32f4_hal.h

@@ -1,3 +1,9 @@
+/*
+ * UART-порт DS2480B для STM32F4. Подготовка линии и очистка ошибок USART отделены от команд
+ * датчика; после сбоя обмена мост должен пройти предусмотренное восстановление до продолжения
+ * работы с 1-Wire.
+ */
+
 #ifndef DS2480_STM32F4_HAL_H
 #define DS2480_STM32F4_HAL_H
 

c/ds18b20-ds2480/ports/stm32f4/tests/stm32f4xx_hal.h

@@ -1,3 +1,11 @@
+/*
+ * Проверки stm32f4xx_hal: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Сценарии для навигации по файлу:
+ *   test_clear
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 /* Host-only HAL model, never add this directory to a firmware include path. */
 #ifndef TEST_STM32F4_HAL_H
 #define TEST_STM32F4_HAL_H

c/ds18b20-ds2480/ports/stm32f4/tests/test_port.c

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

c/ds18b20-ds2480/tests/test_ds18b20_ds2480.c

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

c/ds18b20/CMakeLists.txt

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

c/ds18b20/include/ds18b20.h

@@ -1,3 +1,9 @@
+/*
+ * Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и
+ * настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя
+ * считать действительным до проверки статуса обмена и CRC.
+ */
+
 /**
  * @file ds18b20.h
  * @brief Драйвер термометров DS18B20 поверх шины 1-Wire.

c/ds18b20/include/onewire.h

@@ -1,3 +1,9 @@
+/*
+ * Общие операции 1-Wire и обход дерева 64-битных ROM. Поиск разрешает коллизии побитно,
+ * поэтому обнаружение нескольких устройств не сводится к чтению одного адреса. Электрические
+ * уровни и длительности импульсов задаёт порт.
+ */
+
 /**
  * @file onewire.h
  * @brief Программная шина 1-Wire на выводе с открытым стоком.

c/ds18b20/instance/CMakeLists.txt

@@ -1,3 +1,7 @@
+# Сборка библиотеки ds18b20_instance. Состав исходников и публичные include-пути задают
+# подключение к проекту потребителя. Файл также собирает и регистрирует хостовые проверки;
+# запускать их следует через CTest из каталога сборки.
+
 cmake_minimum_required(VERSION 3.13)
 project(ds18b20_instance C)
 add_library(ds18b20_instance STATIC Src/ds18b20.c)

c/ds18b20/instance/Inc/ds18b20.h

@@ -1,3 +1,9 @@
+/*
+ * Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и
+ * настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя
+ * считать действительным до проверки статуса обмена и CRC.
+ */
+
 #ifndef PORTABLE_DS18B20_H
 #define PORTABLE_DS18B20_H
 

c/ds18b20/instance/Inc/ds18b20_config.h

@@ -1,3 +1,9 @@
+/*
+ * Конфигурация ds18b20. Макросы задают параметры сборки и ограничения, используемые
+ * исходниками этого модуля. Смысл и единицы каждого параметра определяются местом его
+ * использования; размеры буферов должны быть согласованы у всех потребителей заголовка.
+ */
+
 #ifndef PORTABLE_DS18B20_CONFIG_H
 #define PORTABLE_DS18B20_CONFIG_H
 #define DS18B20_DEFAULT_TIMEOUT_MS 750U

c/ds18b20/instance/Src/ds18b20.c

@@ -1,3 +1,9 @@
+/*
+ * Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и
+ * настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя
+ * считать действительным до проверки статуса обмена и CRC.
+ */
+
 #include "ds18b20.h"
 #include "ds18b20_config.h"
 #include <string.h>

c/ds18b20/instance/Tests/run_host_tests.ps1

@@ -1,3 +1,7 @@
+# Сборка и запуск хостовых проверок экземплярного DS18B20. Скрипт готовит исполняемые тесты
+# для проверки поиска ROM и задержек EEPROM без платы; ошибка компиляции или проверки должна
+# завершить прогон неуспешно.
+
 $ErrorActionPreference = "Stop"
 $out = Join-Path $env:TEMP "test_ds18b20_copy_delay.exe"
 $test = Join-Path $PSScriptRoot "test_ds18b20_copy_delay.c"

c/ds18b20/instance/Tests/test_ds18b20_copy_delay.c

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

c/ds18b20/instance/Tests/test_ds18b20_incremental_search.c

@@ -1,3 +1,10 @@
+/*
+ * Проверки ds18b20_incremental_search: фиксируют ожидаемое поведение на воспроизводимых
+ * входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 /* Model real SEARCH ROM participation: each branch filters the active slaves.
  * Fault injection tests transport recovery, not analog cable characteristics. */
 #include "ds18b20.h"

c/ds18b20/ports/stm32f1/onewire_config.f103.template.h

@@ -1,3 +1,9 @@
+/*
+ * Конфигурация ds18b20 для порта stm32f1. Макросы задают параметры сборки и ограничения,
+ * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров
+ * памяти и параметров устройства необходимо согласовать с целевой платой.
+ */
+
 /**
  * @file onewire_config.f103.template.h
  * @brief Шаблон привязки шины 1-Wire для STM32F103 (порт stm32f1).

c/ds18b20/ports/stm32f1/onewire_stm32f1.c

@@ -1,3 +1,9 @@
+/*
+ * Аппаратные временные слоты 1-Wire на STM32F1: управление линией, чтение уровня и
+ * микросекундные задержки. Конфигурация выбирает GPIO и таймер; общий алгоритм поиска ROM
+ * остаётся в onewire.c.
+ */
+
 /**
  * @file onewire_stm32f1.c
  * @brief Порт шины 1-Wire на STM32F1: тайминги, вывод и задержки.

c/ds18b20/ports/stm32f4/onewire_config.f407.template.h

@@ -1,3 +1,9 @@
+/*
+ * Конфигурация ds18b20 для порта stm32f4. Макросы задают параметры сборки и ограничения,
+ * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров
+ * памяти и параметров устройства необходимо согласовать с целевой платой.
+ */
+
 /**
  * @file onewire_config.f407.template.h
  * @brief Шаблон привязки шины 1-Wire для STM32F407VET6 (порт stm32f4).

c/ds18b20/ports/stm32f4/onewire_stm32f4.c

@@ -1,3 +1,9 @@
+/*
+ * Аппаратные временные слоты 1-Wire на STM32F4 с открытым стоком. Порт использует
+ * CMSIS-регистры и параметры onewire_config.h; частота таймера должна соответствовать расчёту
+ * задержек при обмене с датчиками.
+ */
+
 /**
  * @file onewire_stm32f4.c
  * @brief Порт шины 1-Wire на STM32F4: тайминги, вывод и задержки.

c/ds18b20/ports/stm32g4/onewire_config.g431.template.h

@@ -1,3 +1,9 @@
+/*
+ * Конфигурация ds18b20 для порта stm32g4. Макросы задают параметры сборки и ограничения,
+ * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров
+ * памяти и параметров устройства необходимо согласовать с целевой платой.
+ */
+
 /**
  * @file onewire_config.g431.template.h
  * @brief Шаблон привязки шины 1-Wire для STM32G431 (порт stm32g4).

c/ds18b20/ports/stm32g4/onewire_config.g474.template.h

@@ -1,3 +1,9 @@
+/*
+ * Конфигурация ds18b20 для порта stm32g4. Макросы задают параметры сборки и ограничения,
+ * используемые исходниками этого модуля. Это образец для проекта: значения выводов, размеров
+ * памяти и параметров устройства необходимо согласовать с целевой платой.
+ */
+
 /**
  * @file onewire_config.g474.template.h
  * @brief Шаблон привязки шины 1-Wire для STM32G474 (порт stm32g4).

c/ds18b20/ports/stm32g4/onewire_stm32g4.c

@@ -1,3 +1,9 @@
+/*
+ * Аппаратные временные слоты 1-Wire для STM32G431/G474. GPIO и таймер задаются конфигурацией
+ * проекта; чтение уровня выполняется с линии, поэтому паразитное питание и подтяжка относятся
+ * к схеме платы.
+ */
+
 /**
  * @file onewire_stm32g4.c
  * @brief Порт шины 1-Wire на STM32G4: тайминги, вывод и задержки.

c/ds18b20/src/ds18b20.c

@@ -1,3 +1,9 @@
+/*
+ * Работа с термометрами DS18B20: поиск по ROM, запуск преобразования, чтение температуры и
+ * настройка scratchpad. ROM является адресом устройства на общей шине; результат чтения нельзя
+ * считать действительным до проверки статуса обмена и CRC.
+ */
+
 /**  test
  * @file ds18b20.c
  * @brief Реализация драйвера DS18B20: поиск, чтение и запись scratchpad.

c/ds18b20/src/onewire.c

@@ -1,3 +1,9 @@
+/*
+ * Общие операции 1-Wire и обход дерева 64-битных ROM. Поиск разрешает коллизии побитно,
+ * поэтому обнаружение нескольких устройств не сводится к чтению одного адреса. Электрические
+ * уровни и длительности импульсов задаёт порт.
+ */
+
 /**
  * @file onewire.c
  * @brief Переносимая часть шины 1-Wire: побайтовый обмен, CRC8 и поиск ROM.

c/ds18b20/tests/fake_onewire.c

@@ -1,3 +1,9 @@
+/*
+ * Проверки fake_onewire: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 /**
  * @file fake_onewire.c
  * @brief Симулятор шины 1-Wire с виртуальными датчиками DS18B20.

c/ds18b20/tests/fake_onewire.h

@@ -1,3 +1,9 @@
+/*
+ * Проверки fake_onewire: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 /**
  * @file fake_onewire.h
  * @brief Модель шины 1-Wire с виртуальными датчиками для host-тестов.

c/ds18b20/tests/test_ds18b20.c

@@ -1,3 +1,19 @@
+/*
+ * Проверки ds18b20: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Сценарии для навигации по файлу:
+ *   test_crc8
+ *   test_search_finds_all
+ *   test_search_on_empty_bus
+ *   test_search_single_device
+ *   test_scan_filters_family
+ *   test_read_all
+ *   test_crc_error_does_not_stop_the_poll
+ *   test_missing_device_is_reported
+ * Остальные сценарии продолжают эти проверки ниже в том же файле.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 /**
  * Тесты драйвера DS18B20 и переносимой части 1-Wire на симуляторе шины.
  *

c/eeprom-ft24c256/ft24c256.c

@@ -1,3 +1,9 @@
+/*
+ * Доступ к EEPROM семейства 24Cxx через операции I2C порта. Запись разбивается на страницы:
+ * пересечение аппаратной границы одной транзакцией может завернуть адрес внутри страницы.
+ * После записи учитывается время внутреннего программирования.
+ */
+
 /**
  * @file ft24c256.c
  * @brief Постраничная запись, сплошное чтение и ожидание готовности FT24C256.

c/eeprom-ft24c256/ft24c256.h

@@ -1,3 +1,9 @@
+/*
+ * Доступ к EEPROM семейства 24Cxx через операции I2C порта. Запись разбивается на страницы:
+ * пересечение аппаратной границы одной транзакцией может завернуть адрес внутри страницы.
+ * После записи учитывается время внутреннего программирования.
+ */
+
 /**
  * @file ft24c256.h
  * @brief Портируемый драйвер последовательной EEPROM FT24C256 и её семейства.