From 0855239cf3adb3a24d7f34ca1e12bc02163a269e Mon Sep 17 00:00:00 2001
From: abduznik <85239936+abduznik@users.noreply.github.com>
Date: Wed, 2 Sep 2026 10:08:41 +0300
Subject: [PATCH] docs: document GENERIC as a registered, discoverable registry
 key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Issue #148's code half was fixed in #142 (GenericDriver/SimulatedGeneric
register under GENERIC), but the acceptance criterion — 'GENERIC is a
documented, discoverable key' — was unmet: neither the DriverRegistry
docstring nor supported_instruments.md mentioned it.

- registry.py: DriverRegistry docstring now lists GENERIC as an
  always-registered key with both driver classes and its fallback role.
- supported_instruments.md: new 'GENERIC (Universal Fallback)' section
  covering the driver, when it is selected, and its intentionally
  untyped SCPI passthrough API.

Closes the documentation gap for #148.
---
 docs/supported_instruments.md        | 16 ++++++++++++++++
 src/instrumation/drivers/registry.py | 14 +++++++++++++-
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/docs/supported_instruments.md b/docs/supported_instruments.md
index c543196..87398a5 100644
--- a/docs/supported_instruments.md
+++ b/docs/supported_instruments.md
@@ -236,6 +236,22 @@ the same SCPI command set.
 
 ---
 
+## GENERIC (Universal Fallback)
+
+| Driver | Purpose | Auto-Detect IDN Keywords |
+|:---|:---|:---|
+| `GenericDriver` | Catch-all driver for unidentified instruments; accepts any model | none (explicit `"GENERIC"` request or unrecognized `*IDN?`) |
+
+`"GENERIC"` is a first-class, always-registered key in
+`DriverRegistry` — `get_drivers_by_type("GENERIC")` always returns
+`GenericDriver` (real mode) and `SimulatedGeneric` (SIM mode). It is used
+when `connect_instrument()` cannot identify an instrument, or when you
+explicitly pass `driver_type="GENERIC"` to `get_instrument()`. It exposes
+only generic SCPI passthrough (no typed measurement API), so it is a safe
+default, never a silent DMM/SA misread — see issue #148.
+
+---
+
 ## Summary
 
 | Category | Drivers | Validated Models |
diff --git a/src/instrumation/drivers/registry.py b/src/instrumation/drivers/registry.py
index ce42118..d5d6e50 100644
--- a/src/instrumation/drivers/registry.py
+++ b/src/instrumation/drivers/registry.py
@@ -5,7 +5,19 @@
 logger = logging.getLogger(__name__)
 
 class DriverRegistry:
-    """Registry to keep track of available instrument drivers."""
+    """Registry to keep track of available instrument drivers.
+
+    Drivers register themselves against a canonical instrument *type* key
+    (e.g. ``"DMM"``, ``"SA"``, ``"SCOPE"``). The full set of known keys is
+    defined in :data:`instrumation.factory.KNOWN_DRIVER_TYPES`.
+
+    ``"GENERIC"`` is a special, always-registered key: both
+    :class:`instrumation.drivers.generic.GenericDriver` and
+    :class:`instrumation.drivers.simulated.SimulatedGeneric` register
+    against it, so ``get_drivers_by_type("GENERIC")`` never returns an
+    empty list in a normal import. It is the universal fallback used when
+    an instrument cannot be identified (see issue #148).
+    """
     
     # Map of type -> list of driver classes
     _drivers: Dict[str, List[Type[InstrumentDriver]]] = {}