docs: say when a selection read decodes more than the selection

The READMEs said ds[...] reads only the selected elements, and the
facade's read_selection docs that only intersecting chunks are
decompressed. The bounding-box path runs only when the box covers at
most half the dataset; larger boxes (any strided slice across the
dataset), compact, virtual and unwritten datasets and chunked ones with
a non-default fill value decode the whole dataset. The READMEs, the
facade and format docs, the bindings' docstrings and known-issues now
say so, and how index lists are read.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

crates/clawhdf5-py/src/dataset.rs

@@ -1,7 +1,9 @@
 //! PyDataset — h5py-style read access to HDF5 datasets.
 //!
 //! `ds[key]` parses the key into hyperslab selections (see `select`) and
-//! reads only those elements through the facade's `read_selection`; the
+//! reads them through the facade's `read_selection`, which decodes only the
+//! chunks a small selection touches (see its docs for when it decodes the
+//! whole dataset instead); the
 //! bytes it returns become the numpy array's buffer without a copy (see
 //! `convert`). All file access and decoding runs with the GIL released, so
 //! Python threads reading the same or different datasets run in parallel.
@@ -24,7 +26,7 @@ use crate::{PyEmpty, node, to_py_err};
 /// ```python
 /// ds = f['group/dataset']
 /// ds.shape, ds.dtype, ds.attrs['units']
-/// block = ds[10:20, ::2]      # reads only the selected elements
+/// block = ds[10:20, ::2]      # a small selection reads only its chunks
 /// ```
 #[pyclass(name = "Dataset")]
 pub struct PyDataset {
@@ -299,7 +301,8 @@ impl PyDataset {
 
     /// Read with h5py indexing: integers, slices with positive steps,
     /// `...`, one increasing list of integers, and compound field names.
-    /// Only the selected elements are read from the file.
+    /// A selection whose bounding box covers at most half the dataset reads
+    /// only the chunks (or contiguous rows) it overlaps.
     fn __getitem__<'py>(
         &self,
         py: Python<'py>,