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-format/src/data_read.rs

@@ -286,9 +286,11 @@ pub fn read_raw_data_indexed(
 
 /// Read raw bytes for only the selected elements of a dataset.
 ///
-/// For chunked layouts, only chunks that intersect the selection are read
-/// and decompressed. For compact/contiguous layouts, the full data is read
-/// and then the selection is extracted.
+/// When the selection's bounding box covers at most half the dataset, only
+/// that box is materialised — the overlapping rows of a contiguous dataset,
+/// the overlapping chunks of a chunked one, whatever its chunk index (see
+/// [`crate::partial_read`]). Otherwise, and for compact and virtual
+/// layouts, the whole dataset is decoded and the selection extracted.
 #[allow(clippy::too_many_arguments)]
 pub fn read_raw_data_selection(
     file_data: &[u8],