docs: clarify STUN result fields and API usage

src/transport_layer/stun_nat.h

@@ -1,7 +1,8 @@
 /* Определяет поведение NAT через внешние STUN-серверы: совпадает ли внешний IP:порт
  * при обращении к разным IP и доступны ли входящие без предварительного контакта.
  * mapping: MATCH — два сервера видят одинаковый адрес; DEPENDENT — разные;
- * RFC 5780 уточняет EIM/ADM/APDM и filtering (EIF/ADF/APDF). UNKNOWN — данных недостаточно.
+ * RFC 5780 уточняет зависимость mapping: EIM — не зависит от назначения, ADM — от IP, APDM — от IP:порта.
+ * filtering: EIF — незнакомый вход разрешён, ADF — нужен контакт с IP, APDF — с IP:портом. UNKNOWN — данных мало.
  * Для работы: [stun] enabled=yes и минимум две строки server=host[:port] с разными IP.
  * Ядро вызывает init(instance)/destroy(instance), модуль сам измеряет и обновляет результат.
  * get_socket_result(instance, socket, &result) возвращает снимок; recheck(instance) повторяет проверку.
@@ -39,15 +40,16 @@ enum stun_nat_reason {
     STUN_REASON_ROUTE, STUN_REASON_PORTS
 };
 
+/* Снимок одного пути IP/netif; несколько рабочих портов используют общее измерение. */
 struct stun_nat_result {
-    struct stun_nat_key key;
-    uint64_t generation, evidence_id, measured_at_us;
-    unsigned members;
-    int refreshing;
+    struct stun_nat_key key;                    // локальный IP и интерфейс измерения
+    uint64_t generation, evidence_id, measured_at_us; // поколение пути, ID и календарное время результата (мкс)
+    unsigned members;                          // число рабочих сокетов этого пути
+    int refreshing;                            // идёт обновление, пока возвращается действующий кэш
     enum stun_nat_status status;
     enum stun_nat_mapping mapping;
     enum stun_nat_filtering filtering;
-    enum stun_nat_reason mapping_reason, filtering_reason;
+    enum stun_nat_reason mapping_reason, filtering_reason; // причины неполного результата по каждому свойству
     struct sockaddr_storage local;               // адрес независимого тестового UDP-сокета
     struct sockaddr_storage servers[2], mapped[2]; // реальные серверы и наблюдаемые внешние адреса
     unsigned server_count;
@@ -66,8 +68,8 @@ void stun_nat_forget_ports(struct UTUN_INSTANCE* inst);
 void stun_nat_recheck(struct UTUN_INSTANCE* inst);
 /* Копирует результат для имени исходного сокета; -1 если модуль выключен/имя отсутствует. */
 int stun_nat_get_result(const struct UTUN_INSTANCE* inst, const char* socket_name, struct stun_nat_result* result);
-/* Проверяет принадлежность текущего рабочего сокета группе и её routing options.
- * Во время refresh возвращает ещё действующий кэш; время кэша не омолаживается. */
+/* Записывает в result снимок пути socket из instance; 0 — готово, -1 — подходящего пути нет.
+ * Проверяет IP, интерфейс и routing options. Во время refresh возвращает действующий кэш с прежним временем. */
 int stun_nat_get_socket_result(const struct UTUN_INSTANCE* inst, const struct ETCP_SOCKET* socket, struct stun_nat_result* result);
 const char* stun_nat_mapping_name(enum stun_nat_mapping value);
 const char* stun_nat_filtering_name(enum stun_nat_filtering value);