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

@@ -525,8 +525,16 @@ impl<'f> Dataset<'f> {
 
     /// Read selected elements as raw bytes.
     ///
-    /// Only the elements matching the [`clawhdf5_format::selection::Selection`] are returned. For chunked
-    /// datasets, only intersecting chunks are decompressed.
+    /// Only the elements matching the [`clawhdf5_format::selection::Selection`] are returned.
+    ///
+    /// What is read to get them: when the selection's bounding box covers at
+    /// most half the dataset, only that box — the chunks overlapping it, or
+    /// the rows of a contiguous dataset. The whole dataset is decoded instead
+    /// when the box covers more than half (a strided selection spanning the
+    /// dataset does), for compact and virtual layouts, for a dataset with no
+    /// storage, and for a chunked dataset with a non-default fill value.
+    /// [`Selection::All`](clawhdf5_format::selection::Selection::All) goes
+    /// through the file's chunk cache; other selections do not.
     pub fn read_selection(
         &self,
         selection: &clawhdf5_format::selection::Selection,