From eac946d9b91ad09b623fe4a636217d6cbadf01a9 Mon Sep 17 00:00:00 2001
From: "qwen.ai[bot]" <qwenlm-intl@service.alibaba.com>
Date: Wed, 12 Aug 2026 14:51:05 +0000
Subject: [PATCH] docs: add docstrings to score_vpn and assess_vpn

---
 src/netsleuth/interpret.py | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/src/netsleuth/interpret.py b/src/netsleuth/interpret.py
index 97917fc..ef81a4a 100644
--- a/src/netsleuth/interpret.py
+++ b/src/netsleuth/interpret.py
@@ -283,6 +283,17 @@ def gather_vpn_signals(ctx: VpnContext) -> list[Signal]:
 
 
 def score_vpn(signals: list[Signal], bands: VpnBands) -> tuple[str, float]:
+    """Calculate VPN confidence score from observed signals.
+
+    Args:
+        signals: List of Signal objects with weights and observed flags.
+        bands: VpnBands with 'likely' and 'confirmed' thresholds.
+
+    Returns:
+        A tuple of (verdict, confidence) where verdict is one of
+        'confirmed', 'likely', or 'none', and confidence is a float
+        between 0.0 and 1.0 representing the accumulated weight.
+    """
     total = 0.0
     for s in signals:
         if not s.observed:
@@ -302,6 +313,18 @@ def assess_vpn(
     tunnel_iface: str | None,
     dns_leak: DnsLeak | None,
 ) -> VpnAssessment:
+    """Build a VPN assessment from signals and context.
+
+    Args:
+        signals: List of Signal objects from gather_vpn_signals.
+        bands: VpnBands containing verdict thresholds.
+        tunnel_iface: Name of the tunnel interface if detected.
+        dns_leak: DnsLeak object if DNS leak testing was performed.
+
+    Returns:
+        A VpnAssessment object with verdict, confidence score,
+        all signals, tunnel interface name, and DNS leak data.
+    """
     verdict, confidence = score_vpn(signals, bands)
     return VpnAssessment(
         verdict=verdict,