Add example how to use Blobs::reader

Author: rklaehn

src/api.rs

@@ -4,7 +4,7 @@
 //! with a remote store via rpc calls.
 //!
 //! The entry point for the api is the [`Store`] struct. There are several ways
-//! to obtain a `Store` instance: it is available via [`Deref`](std::ops::Deref)
+//! to obtain a `Store` instance: it is available via [`Deref`]
 //! from the different store implementations
 //! (e.g. [`MemStore`](crate::store::mem::MemStore)
 //! and [`FsStore`](crate::store::fs::FsStore)) as well as on the

src/api/blobs.rs

@@ -105,10 +105,34 @@ impl Blobs {
         })
     }
 
+    /// Create a reader for the given hash. The reader implements [`tokio::io::AsyncRead`] and [`tokio::io::AsyncSeek`]
+    /// and therefore can be used to read the blob's content.
+    ///
+    /// Any access to parts of the blob that are not present will result in an error.
+    ///
+    /// Example:
+    /// ```rust
+    /// use iroh_blobs::{store::mem::MemStore, api::blobs::Blobs};
+    /// use tokio::io::AsyncReadExt;
+    ///
+    /// # async fn example() -> anyhow::Result<()> {
+    /// let store = MemStore::new();
+    /// let tag = store.add_slice(b"Hello, world!").await?;
+    /// let mut reader = store.reader(tag.hash);
+    /// let mut buf = String::new();
+    /// reader.read_to_string(&mut buf).await?;
+    /// assert_eq!(buf, "Hello, world!");
+    /// # Ok(())
+    /// }
+    /// ```
     pub fn reader(&self, hash: impl Into<Hash>) -> BlobReader {
         self.reader_with_opts(ReaderOptions { hash: hash.into() })
     }
 
+    /// Create a reader for the given options. The reader implements [`tokio::io::AsyncRead`] and [`tokio::io::AsyncSeek`]
+    /// and therefore can be used to read the blob's content.
+    ///
+    /// Any access to parts of the blob that are not present will result in an error.
     pub fn reader_with_opts(&self, options: ReaderOptions) -> BlobReader {
         BlobReader::new(self.clone(), options)
     }

src/api/blobs/reader.rs

@@ -11,6 +11,7 @@ use crate::api::{
     proto::ExportRangesItem,
 };
 
+/// A reader for blobs that implements `AsyncRead` and `AsyncSeek`.
 #[derive(Debug)]
 pub struct BlobReader {
     blobs: Blobs,
@@ -298,7 +299,6 @@ mod tests {
     async fn reader_partial_fs() -> TestResult<()> {
         let testdir = tempfile::tempdir()?;
         let store = FsStore::load(testdir.path().to_owned()).await?;
-        // reader_smoke_raw(store.blobs()).await?;
         reader_partial(store.blobs()).await?;
         Ok(())
     }
@@ -314,7 +314,6 @@ mod tests {
     async fn reader_smoke_fs() -> TestResult<()> {
         let testdir = tempfile::tempdir()?;
         let store = FsStore::load(testdir.path().to_owned()).await?;
-        // reader_smoke_raw(store.blobs()).await?;
         reader_smoke(store.blobs()).await?;
         Ok(())
     }