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

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 на симуляторе шины.
  *