Consolidate sliding minimum documentation in header

lib/swm_min.h

@@ -1,5 +1,6 @@
 /* swm_min — минимум последних window_size целых значений (окно по числу добавлений, не по времени).
- * create → add/get_min → destroy; память окна выделяется при create, внутренняя синхронизация отсутствует. */
+ * create → add/get_min → destroy; память O(window_size) выделяется при create, внутренней синхронизации нет.
+ * Монотонный deque: add амортизированно O(1), get_min O(1); значения int, включая отрицательные. */
 #ifndef SLIDING_WINDOW_MIN_H
 #define SLIDING_WINDOW_MIN_H
 
@@ -14,24 +15,28 @@ typedef struct SlidingWindowMin SlidingWindowMin;
 /**
  * Создаёт новую структуру скользящего минимума.
  * @param window_size  размер окна (должен быть > 0)
- * @return указатель на структуру или NULL при ошибке выделения памяти
+ * @return указатель на структуру или NULL при window_size <= 0 / ошибке выделения памяти
  */
 SlidingWindowMin* swm_create(int window_size);
 
 /**
  * Уничтожает структуру и освобождает всю динамически выделенную память.
+ * @param swm окно; NULL допустим
  */
 void swm_destroy(SlidingWindowMin* swm);
 
 /**
  * Добавляет новое значение в окно.
+ * @param swm окно; при NULL ничего не делает
+ * @param val новое целое значение
  * После вызова swm_get_min() сразу вернёт минимум последних min(window_size, добавленных) значений.
  */
 void swm_add(SlidingWindowMin* swm, int val);
 
 /**
  * Возвращает текущий минимум в окне.
- * Если окно пустое — возвращает INT_MAX.
+ * @param swm окно
+ * @return минимум; если окно пустое или swm == NULL — INT_MAX
  */
 int swm_get_min(const SlidingWindowMin* swm);
 

lib/swm_min_doc.md

@@ -1,39 +0,0 @@
-# Sliding Window Minimum (swm_min.h)
-
-## 1. Назначение
-Структура данных для отслеживания минимума в скользящем окне фиксированного размера. Добавление значения и запрос минимума — O(1) амортизированное время. Память — O(window_size). Предназначена для отслеживания минимального RTT в ETCP/BBR (в кодовой базе зарезервирована, ожидает интеграции).
-
-## 2. Как пользоваться
-Создать окно заданного размера, добавлять значения по мере поступления, запрашивать текущий минимум.
-
-```c
-SlidingWindowMin *swm = swm_create(10); // окно из 10 последних значений
-
-for (int i = 0; i < 100; i++) {
-    swm_add(swm, get_new_rtt());
-    int min_rtt = swm_get_min(swm); // минимум последних ≤10 значений
-}
-
-swm_destroy(swm);
-```
-
-**Нюансы:**
-- `swm_get_min` на пустом окне возвращает `INT_MAX`
-- `window_size` должен быть > 0, иначе `swm_create` вернёт NULL
-- Значения — `int`, отрицательные допустимы
-
-## 3. API
-
-### Структура
-- **`SlidingWindowMin`** — непрозрачная структура (opaque pointer). Содержит кольцевой буфер значений, deque индексов, позицию и размер окна.
-
-### Функции
-- **`swm_create(window_size)`** — выделяет SlidingWindowMin, инициализирует пустой deque и кольцевой буфер размера `window_size`. Возвращает NULL при ошибке выделения памяти.
-- **`swm_destroy(swm)`** — освобождает все ресурсы структуры.
-- **`swm_add(swm, val)`** — добавляет значение в окно. Автоматически вытесняет индексы, вышедшие за границу окна, и удаляет из deque значения, которые больше текущего (поддерживает монотонный минимум).
-- **`swm_get_min(swm)`** — возвращает минимум текущего окна за O(1). Для пустого окна — `INT_MAX`.
-
-### Алгоритм
-Использует монотонный deque: в голове deque всегда индекс минимального элемента текущего окна. При добавлении из хвоста удаляются элементы ≥ нового — они никогда не станут минимумом, пока новый элемент в окне.
-
-Тест: `tests/test_swm_min.c`