From c0a92a618469fb44c843b927bd3d3276a2732d7b Mon Sep 17 00:00:00 2001
From: dangotbanned <125183946+dangotbanned@users.noreply.github.com>
Date: Thu, 30 Jan 2025 18:16:12 +0000
Subject: [PATCH] docs: Add docs for `Read`, `Scan`, `BaseImpl`

---
 altair/datasets/_reader.py   | 11 +----------
 altair/datasets/_readimpl.py | 33 +++++++++++++++++++++++++++++----
 2 files changed, 30 insertions(+), 14 deletions(-)

diff --git a/altair/datasets/_reader.py b/altair/datasets/_reader.py
index c06fdc9cc..2162d910c 100644
--- a/altair/datasets/_reader.py
+++ b/altair/datasets/_reader.py
@@ -106,20 +106,11 @@ class Reader(Generic[IntoDataFrameT, IntoFrameT]):
         Use ``reader(...)`` instead of instantiating ``Reader`` directly.
     """
 
-    # TODO: Docs
     _read: Sequence[Read[IntoDataFrameT]]
     """Eager file read functions."""
 
-    # TODO: Docs
     _scan: Sequence[Scan[IntoFrameT]]
-    """
-    *Optionally*-lazy file read/scan functions.
-
-    Used exclusively for ``metadata.parquet``.
-
-    Currently ``"polars"`` is the only lazy option.
-    All others defer to the eager variant.
-    """
+    """Lazy file read functions."""
 
     _name: str
     """
diff --git a/altair/datasets/_readimpl.py b/altair/datasets/_readimpl.py
index 0278d48b5..cc4c01e07 100644
--- a/altair/datasets/_readimpl.py
+++ b/altair/datasets/_readimpl.py
@@ -56,8 +56,11 @@
     bound="nwt.NativeFrame | nw.DataFrame[Any] | nw.LazyFrame | nwt.DataFrameLike",
     default=nw.LazyFrame,
 )
-Scan = TypeAliasType("Scan", "BaseImpl[IntoFrameT]", type_params=(IntoFrameT,))
 Read = TypeAliasType("Read", "BaseImpl[IntoDataFrameT]", type_params=(IntoDataFrameT,))
+"""An *eager* file read function."""
+
+Scan = TypeAliasType("Scan", "BaseImpl[IntoFrameT]", type_params=(IntoFrameT,))
+"""A *lazy* file read function."""
 
 
 class Skip(Enum):
@@ -73,12 +76,33 @@ def __repr__(self) -> Literal["<Skip>"]:
 
 
 class BaseImpl(Generic[R]):
+    """
+    A function wrapped with dataset support constraints.
+
+    The ``include``, ``exclude`` properties form a `NIMPLY gate`_ (`Material nonimplication`_).
+
+    Examples
+    --------
+    For some dataset ``D``, we can use ``fn`` if::
+
+        impl: BaseImpl
+        impl.include(D) and not impl.exclude(D)
+
+
+    .. _NIMPLY gate:
+        https://en.m.wikipedia.org/wiki/NIMPLY_gate
+    .. _Material nonimplication:
+        https://en.m.wikipedia.org/wiki/Material_nonimplication#Truth_table
+    """
+
     fn: Callable[..., R]
-    """Wrapped read function."""
+    """Wrapped read/scan function."""
+
     include: MetaIs
-    """Passing this makes ``fn`` a candidate."""
+    """Constraint indicating ``fn`` **supports** reading a dataset."""
+
     exclude: MetaIs
-    """Passing this overrides ``include``, transforming into an error."""
+    """Constraint *subsetting* ``include`` to mark **non-support**."""
 
     def __init__(
         self,
@@ -121,6 +145,7 @@ def unwrap_or_skip(
 
     @classmethod
     def _exclude_none(cls) -> MetaIs:
+        """Represents the empty set."""
         return is_meta()
 
     def __setattr__(self, name: str, value: Any):