docs: подробные docstring перед каждой функцией

api/db.py

@@ -28,13 +28,16 @@ class Database:
         self._init_schema()
 
     def __enter__(self):
+        """Контекстный менеджер: with Database() as db."""
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
+        """Закрытие соединения при выходе из with-блока."""
         self.close()
         return False
 
     def close(self):
+        """Закрыть соединение с SQLite."""
         if self.conn:
             self.conn.close()
             self.conn = None

api/dtc.py

@@ -19,6 +19,7 @@ _DTC_PATH = Path(__file__).parent.parent / "doc" / "dtc_codes.txt"
 
 
 def _load_dtc_dict() -> dict[str, str]:
+    """Загрузить справочник DTC-кодов из doc/dtc_codes.txt."""
     global _DTC_CODES
     if _DTC_CODES:
         return _DTC_CODES

obd/protocol.py

@@ -180,6 +180,7 @@ class AndrOBD:
         return raw
 
     def _recover(self):
+        """Восстановление после ошибки: ATWS → ATSP0 → ATE0."""
         """Восстановление после ошибки: ATWS → ATSP0 → ATE0."""
         logger.info("AndrOBD: recovering...")
         self._state = State.INITIALIZING
@@ -192,7 +193,7 @@ class AndrOBD:
         self._state = State.READY
 
     def _write(self, cmd: str):
-        """Отправить команду в ELM327 (добавляет CR, flush)."""
+        """Отправить команду в ELM327: сброс буфера → write + CR → flush."""
         self._ser.reset_input_buffer()  # сбросить хвосты предыдущего ответа
         self._ser.write((cmd + "\r").encode())
         self._ser.flush()

obd/state.py

@@ -51,7 +51,7 @@ class Rsp:
 
     @classmethod
     def identify(cls, raw: str) -> str:
-        """Определяет тип ответа по сырой строке."""
+        """Определяет тип ответа ELM327 по сырой строке."""
         u = raw.upper().strip()
         # NO DATA бывает как "NODATA" так и "NO DATA"
         if u.replace(" ", "") == "NODATA":

obd/timing.py

@@ -21,6 +21,7 @@ class AdaptiveTiming:
     RES     = 4     # делитель для ATST
 
     def __init__(self):
+        """Начальный таймаут = DEFAULT."""
         self._t = self.DEFAULT
         self._min = self.MIN
 
@@ -35,15 +36,18 @@ class AdaptiveTiming:
         return max(1, self._t // self.RES)
 
     def increase(self):
+        """Увеличить таймаут на STEP (ЭБУ медленно отвечает)."""
         """Увеличить таймаут (ЭБУ медленно отвечает)."""
         if self._t + self.STEP < self.MAX:
             self._t += self.STEP
 
     def decrease(self):
+        """Уменьшить таймаут на STEP (ЭБУ отвечает быстро)."""
         """Уменьшить таймаут (ЭБУ отвечает быстро)."""
         if self._t - self.STEP >= self._min:
             self._t -= self.STEP
 
     def reset(self):
+        """Сброс до DEFAULT (после BUS ERROR / инициализации)."""
         """Сбросить до DEFAULT (после BUS ERROR)."""
         self._t = self.DEFAULT