read: more ReadRef and ReadCache documentation (#633)

src/read/read_cache.rs

@@ -17,6 +17,12 @@ use crate::read::ReadRef;
 /// them to be returned. Entries in the cache are never removed.
 /// Entries are keyed on the offset and size of the read.
 /// Currently overlapping reads are considered separate reads.
+///
+/// This is primarily intended for environments where memory mapped files
+/// are not available or not suitable, such as WebAssembly.
+///
+/// Note that malformed files can cause the cache to grow much larger than
+/// the file size.
 #[derive(Debug)]
 pub struct ReadCache<R: Read + Seek> {
     cache: RefCell<ReadCacheInternal<R>>,
@@ -160,7 +166,7 @@ impl<'a, R: Read + Seek> ReadRef<'a> for &'a ReadCache<R> {
 /// An implementation of [`ReadRef`] for a range of data in a stream that
 /// implements `Read + Seek`.
 ///
-/// Shares an underlying `ReadCache` with a lifetime of `'a`.
+/// Shares an underlying [`ReadCache`] with a lifetime of `'a`.
 #[derive(Debug)]
 pub struct ReadCacheRange<'a, R: Read + Seek> {
     r: &'a ReadCache<R>,

src/read/read_ref.rs

@@ -16,6 +16,18 @@ type Result<T> = result::Result<T, ()>;
 /// - the block of data exists in storage, and it is desirable
 ///   to read on demand to minimize I/O and memory usage.
 ///
+/// A block of data typically exists in memory as a result of using a memory
+/// mapped file, and the crate was written with this use case in mind.
+/// Reading the entire file into a `Vec` is also possible, but it often uses
+/// more I/O and memory.
+/// Both of these are handled by the `ReadRef` implementation for `&[u8]`.
+///
+/// For the second use case, the `ReadRef` trait is implemented for
+/// [`&ReadCache`](super::ReadCache). This is useful for environments where
+/// memory mapped files are not available or not suitable, such as WebAssembly.
+/// This differs from reading into a `Vec` in that it only reads the portions
+/// of the file that are needed for parsing.
+///
 /// The methods accept `self` by value because `Self` is expected to behave
 /// similar to a reference: it may be a reference with a lifetime of `'a`,
 /// or it may be a wrapper of a reference.