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

2026-10-02 16:46:19 +03:00
parent 6cbce6c360
commit 427fc70100
488 changed files with 2877 additions and 1 deletions
@@ -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)
@@ -1,3 +1,9 @@
+/*
+ * Команды DS18B20 поверх интерфейса DS2480B: адресация ROM, преобразование температуры и
+ * scratchpad. Транспортный статус следует проверять до использования результата; сырая
+ * температура сохраняет знаковое представление датчика.
+ */
+
 #include "ds18b20_ds2480.h"
 #include <string.h>

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

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

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

 /* board_port supplies the four callbacks documented in ds2480.h.
@@ -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)
@@ -1,3 +1,9 @@
+/*
+ * UART-порт DS2480B для STM32F4. Подготовка линии и очистка ошибок USART отделены от команд
+ * датчика; после сбоя обмена мост должен пройти предусмотренное восстановление до продолжения
+ * работы с 1-Wire.
+ */
+
 #ifndef DS2480_STM32F4_HAL_H
 #define DS2480_STM32F4_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
@@ -1,3 +1,11 @@
+/*
+ * Проверки port: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Сценарии для навигации по файлу:
+ *   test_clear
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 #include "ds2480_stm32f4_hal.h"
 #include <assert.h>
 #include <stdio.h>
@@ -1,3 +1,9 @@
+/*
+ * Проверки ds18b20_ds2480: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 #include "ds18b20_ds2480.h"
 #include <stdio.h>
 #include <stdlib.h>