diff --git a/lib/async_dns.h b/lib/async_dns.h
index 9ebeea6b..c1dd5c7f 100644
--- a/lib/async_dns.h
+++ b/lib/async_dns.h
@@ -34,23 +34,27 @@ struct adns_result {
     struct sockaddr_in addrs[ADNS_MAX_ADDRS];  /* AF_INET, sin_port = 0 */
 };
 
+/* res заимствован до возврата callback; handle запроса к этому моменту уже освобождён. */
 typedef void (*adns_done_cb)(const struct adns_result* res, void* arg);
 
 struct adns_opts {
     struct sockaddr_in server;   /* sin_family != 0 → использовать этот сервер (иначе системные) */
-    int timeout_ms;              /* таймаут на сервер, по умолчанию 2000 */
+    int timeout_ms;              /* Таймаут на сервер в мс; <=0 → 2000, округляется вверх до целых секунд. */
     int max_attempts;            /* попыток на сервер, по умолчанию 2 */
 };
 
 struct adns_query;  /* opaque */
 
 /* Запускает асинхронный A-запрос. Коллбэк вызывается в потоке event loop.
-   Возвращает handle (NULL при немедленной ошибке: невалидные аргументы/нет памяти). */
+ * Возвращает handle, автоматически освобождаемый до callback либо при отмене.
+ * NULL: неверные аргументы, нехватка памяти, отсутствие DNS-серверов, ошибка создания
+ * резолвера, постановки запроса или регистрации отложенного запуска; callback не вызывается. */
 struct adns_query* adns_resolve(struct UASYNC* ua, const char* name,
                                 const struct adns_opts* opts,
                                 adns_done_cb cb, void* arg);
 
-/* Отмена ожидающего запроса: коллбэк НЕ вызывается. Только из потока loop. */
+/* Отмена ожидающего запроса: освобождает handle, коллбэк НЕ вызывается. Только из потока loop.
+ * После завершения/отмены handle недействителен; NULL допустим. */
 void adns_cancel(struct adns_query* q);
 
 /* Системные DNS-серверы (IPv4). Возвращает количество; out[].sin_port = htons(53).
diff --git a/lib/json_flat.h b/lib/json_flat.h
index 55401eb0..125ad0eb 100644
--- a/lib/json_flat.h
+++ b/lib/json_flat.h
@@ -5,6 +5,8 @@
  * Только строковые значения и обычные escapes; \uXXXX не поддерживается.
  * Callback получает полные key/value, действительные только до его возврата.
  * parse возвращает 0 при успехе/остановке callback, -1 при ошибке; остановка не проверяет остаток ввода.
+ * Синтаксис проверяется нестрого: допускаются пропущенные и завершающие запятые;
+ * хвост после закрывающей } игнорируется даже без остановки callback.
  * get ищет первый ключ и копирует значение с NUL, при малом буфере обрезает; 0 найден, -1 ошибка/нет ключа.
  */
 
diff --git a/lib/video_plane.h b/lib/video_plane.h
index d9931847..2ceacb79 100644
--- a/lib/video_plane.h
+++ b/lib/video_plane.h
@@ -9,13 +9,14 @@
 extern "C" {
 #endif
 
-/* data — первый пиксель, size — доступные байты от него; stride — шаг строки/пикселя. */
+/* data — первый пиксель, size — доступные байты от него.
+ * row_stride — шаг строки 1..16777216 байт, pixel_stride — шаг пикселя 1..4096 байт. */
 struct video_plane {
     uint8_t *data;
     size_t size, row_stride, pixel_stride;
 };
 
-/* src_width/height — размеры источника; rotation — 0/90/180/270 градусов.
+/* src_width/height — размеры источника, каждый 1..4096; rotation — 0/90/180/270 градусов.
  * При 90/270 размеры назначения переставлены. Возвращает 0 либо -1 с диагностикой;
  * все границы проверяются до первой записи. */
 int video_plane_rotate(const struct video_plane *src, const struct video_plane *dst,