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,6 @@
+# Сборка общей библиотеки SETProtocol средствами Android NDK. C-ядро и JNI-обёртки входят в
+# один модуль; список исходников должен включать реализации всех native-методов Kotlin.
+
 LOCAL_PATH := $(call my-dir)

 include $(CLEAR_VARS)
@@ -1,3 +1,8 @@
+/*
+ * Kotlin-модель обмена с мостом CAN/RS485. Преобразование wire-кадров делегируется общему
+ * ядру; пользовательский интерфейс получает типизированные поля, не зависящие от JNI-массивов.
+ */
+
 package ru.setcorp.setflash.core

 import ru.setcorp.setprotocol.NativeSetProtocol as NativeProtoCan
@@ -1,3 +1,9 @@
+/*
+ * Кадрирование исторического GUI protocol v1. Parser накапливает части входного потока и
+ * проверяет сообщение до выдачи результата; этот формат следует выбирать по профилю
+ * соединения, а не только по сигнатуре.
+ */
+
 package ru.setcorp.setflash.core

 import java.util.zip.CRC32
@@ -1,3 +1,8 @@
+/*
+ * Общий каталог типов сообщений ProtoCAN для Android-клиентов. Числовые коды являются частью
+ * протокола; подписи служат отображению и не должны использоваться вместо кодов в обмене.
+ */
+
 package ru.setcorp.setflash.core

 /** Canonical ProtoCAN message-type registry shared by Android protocol clients. */
@@ -1,3 +1,8 @@
+/*
+ * Kotlin-фасад протокола BALZAM/TMS320F2812. Кадрирование и контрольные суммы выполняет
+ * C99-ядро через NativeSetProtocol; модели Kotlin описывают аргументы и результаты операций.
+ */
+
 package ru.setcorp.setflash.core

 import ru.setcorp.setprotocol.NativeSetProtocol
@@ -1,3 +1,8 @@
+/*
+ * Kotlin-объявления JNI-вызовов общего SETProtocol. Порядок и типы аргументов должны совпадать
+ * с setprotocol_jni.c; библиотека должна содержать все объявленные нативные символы.
+ */
+
 package ru.setcorp.setprotocol

 /** Thin Kotlin facade over the shared C99 SETProtocol core. */
@@ -1,3 +1,8 @@
+/*
+ * Android-представление исторического CAN-протокола BALZAM. Код связывает Kotlin-модели с
+ * общим ядром; регистры и формат идентификаторов не относятся к протоколу ПМ35.
+ */
+
 package ru.setcorp.setprotocol.balsam

 import ru.setcorp.setprotocol.NativeSetProtocol
@@ -1,3 +1,9 @@
+/*
+ * Android-модель исторического CAN-терминала и выбора проекта. Каталог определяет семантику
+ * команд, а транспорт только доставляет CAN-кадры; UI не должен создавать собственную копию
+ * wire-формата.
+ */
+
 package ru.setcorp.setprotocol.legacycan

 /** Wire formats implemented by the historical CAN_terminal application. */
@@ -1,3 +1,8 @@
+/*
+ * Android-фасад отдельного протокола ПМ35/TMS320F28335. Запросы и ответы преобразуются через
+ * общее ядро; профиль периферийного контроллера сохраняется отдельно от TMS320F2812.
+ */
+
 package ru.setcorp.setprotocol.periph28335

 import ru.setcorp.setprotocol.NativeSetProtocol
@@ -1,3 +1,9 @@
+/*
+ * Android-поддержка наблюдения за объектами GAS через GUI-протокол. Подписка связывает список
+ * выбранных адресов с поступающими значениями; смена выбора требует согласования состояния
+ * клиента.
+ */
+
 package ru.setcorp.setprotocol.trends

 import ru.setcorp.setprotocol.NativeSetProtocol
@@ -1,3 +1,9 @@
+/*
+ * Адаптер общей математики графика из set_plot.c. Область просмотра и координатные
+ * преобразования рассчитываются ядром; приложение отвечает за единицы, получение измерений и
+ * отрисовку.
+ */
+
 package ru.setcorp.setprotocol.trends

 /** Shared C99 plot math, also used by the Python/Qt port. No UI dependency. */
@@ -1,3 +1,8 @@
+/*
+ * Модель области просмотра графика для Android. Границы и преобразования координат связывают
+ * жесты интерфейса с общей математикой; изменение видимой области не меняет измеренные данные.
+ */
+
 package ru.setcorp.setprotocol.trends

 /** Normalized top-left viewport; independent of pixels, units, toolkit and samples. */
@@ -1,3 +1,8 @@
+/*
+ * Android-адаптер декодирования источников трендов. Сырые данные интерпретируются по типу
+ * источника и его параметрам, а результаты передаются модели отображения в числовом виде.
+ */
+
 package ru.setcorp.setprotocol.trends

 import ru.setcorp.setprotocol.NativeSetProtocol
@@ -1,3 +1,9 @@
+/*
+ * Состояние измерительных маркеров и линеек графика. Маркер относится к координатам
+ * отображаемого сигнала; его перемещение не изменяет полученные выборки или настройки
+ * транспорта.
+ */
+
 package ru.setcorp.setprotocol.trends

 import kotlin.math.abs
@@ -1,3 +1,9 @@
+/*
+ * Модели источников и настроек трендов, используемые клиентскими приложениями. Идентификатор
+ * сигнала связывает историю с источником независимо от имени и порядка; визуальное
+ * переименование не должно менять физический источник.
+ */
+
 package ru.setcorp.setprotocol.trends

 import java.util.UUID
@@ -1,3 +1,9 @@
+/*
+ * Чтение и запись общего JSON-контракта настроек трендов. Стабильные идентификаторы и версия
+ * формата нужны для обмена настройками между Android и Python; UI-порядок не заменяет
+ * идентичность сигнала.
+ */
+
 package ru.setcorp.setprotocol.trends

 import org.json.JSONArray
@@ -1,3 +1,9 @@
+/*
+ * Привязка общего расчёта спектра C99 к клиенту. Входные временные метки задаются в секундах;
+ * частота дискретизации и нормировка определяются ядром, поэтому отображение не должно
+ * повторно нормировать амплитуды.
+ */
+
 package ru.setcorp.setprotocol.trends

 import ru.setcorp.setprotocol.NativeSetProtocol
@@ -1,3 +1,9 @@
+/*
+ * Модель каталога firmware.releases и проверка записей update.json. Метаданные выпуска
+ * описывают совместимость и расположение образа; выбор записи и последующее скачивание
+ * являются отдельными операциями.
+ */
+
 package ru.setcorp.setprotocol.update

 import android.util.Base64
@@ -1,3 +1,9 @@
+/*
+ * Граница JNI между Kotlin и общим C-ядром. Массивы и примитивные значения Java преобразуются
+ * в аргументы C; полученные через JNI указатели имеют ограниченное время жизни и должны
+ * освобождаться по правилам JNI.
+ */
+
 #include <jni.h>
 #include "set_plot.h"

@@ -1,3 +1,9 @@
+/*
+ * Граница JNI между Kotlin и общим C-ядром. Массивы и примитивные значения Java преобразуются
+ * в аргументы C; полученные через JNI указатели имеют ограниченное время жизни и должны
+ * освобождаться по правилам JNI.
+ */
+
 #include <jni.h>
 #include <stdint.h>
 #include <stdlib.h>
@@ -1,3 +1,9 @@
+/*
+ * Проверки ProtoCanCatalog: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 package ru.setcorp.setflash.core

 import org.junit.Assert.assertEquals
@@ -1,3 +1,9 @@
+/*
+ * Проверки TmsTerminalShared: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 package ru.setcorp.setflash.core

 import org.junit.Assert.*
@@ -1,3 +1,9 @@
+/*
+ * Проверки BalsamCanProtocol: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 package ru.setcorp.setprotocol.balsam

 import org.junit.Assert.assertEquals
@@ -1,3 +1,9 @@
+/*
+ * Проверки LegacyCanTerminal: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 package ru.setcorp.setprotocol.legacycan

 import org.junit.Assert.assertEquals
@@ -1,3 +1,10 @@
+/*
+ * Проверки Periph28335Protocol: фиксируют ожидаемое поведение на воспроизводимых входных
+ * данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 package ru.setcorp.setprotocol.periph28335

 import org.junit.Assert.assertEquals
@@ -1,3 +1,9 @@
+/*
+ * Проверки GuiGasWatch: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 package ru.setcorp.setprotocol.trends

 import org.junit.Assert.*
@@ -1,3 +1,9 @@
+/*
+ * Проверки PlotContract: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 package ru.setcorp.setprotocol.trends

 import org.json.JSONObject
@@ -1,3 +1,9 @@
+/*
+ * Проверки PlotViewport: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 package ru.setcorp.setprotocol.trends

 import org.junit.Assert.*
@@ -1,3 +1,9 @@
+/*
+ * Проверки TrendSettingsJson: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+ * Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+ * настройками рабочего устройства.
+ */
+
 package ru.setcorp.setprotocol.trends

 import org.json.JSONObject