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

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

diff --git a/src/netsleuth/interpret.py b/src/netsleuth/interpret.py
index ef81a4a..e8a08ff 100644
--- a/src/netsleuth/interpret.py
+++ b/src/netsleuth/interpret.py
@@ -357,6 +357,16 @@ _GRADE_SEVERITY = {"A": "ok", "B": "ok", "C": "warn", "D": "crit", "E": "crit",
 
 
 def grade_bufferbloat(delta_ms: float | None, bands: BufferbloatBands) -> str:
+    """Assign a bufferbloat grade (A-F or ?) from RTT delta.
+
+    Args:
+        delta_ms: The increase in RTT under load (bufferbloat), in ms.
+            None means unmeasured.
+        bands: BufferbloatBands with thresholds for grades A through E.
+
+    Returns:
+        A single-letter grade: 'A' through 'F', or '?' if delta_ms is None.
+    """
     if delta_ms is None:
         return "?"
     delta = max(0.0, delta_ms)
@@ -367,11 +377,31 @@ def grade_bufferbloat(delta_ms: float | None, bands: BufferbloatBands) -> str:
 
 
 def bufferbloat_consequence(grade: str, lang: str = "en") -> str:
+    """Return a human-readable explanation of a bufferbloat grade.
+
+    Args:
+        grade: A bufferbloat grade ('A' through 'F', or '?').
+        lang: Language code ('en' or 'ru').
+
+    Returns:
+        A sentence describing the user impact of that grade in the
+        requested language, or the default message for unknown grades.
+    """
     table = _CONSEQUENCES_RU if lang == "ru" else _CONSEQUENCES
     return table.get(grade, table["?"])
 
 
 def speed_findings(speed: SpeedResult, bands: BufferbloatBands) -> list[Finding]:
+    """Generate findings from speedtest results and bufferbloat analysis.
+
+    Args:
+        speed: A SpeedResult object containing throughput and RTT data.
+        bands: BufferbloatBands with thresholds for grading bufferbloat.
+
+    Returns:
+        A list of Finding objects describing issues like missing measurements,
+        excessive bufferbloat during download or upload, or other anomalies.
+    """
     if speed.method == "none":
         tried = ", ".join(a.tier for a in speed.tier_attempts) or "none"
         return [