From 3f51a8ffc2f232532706336f374b946cdbe9d12c Mon Sep 17 00:00:00 2001
From: Floris Bruynooghe <flub@devork.be>
Date: Fri, 10 Feb 2023 10:48:10 +0100
Subject: [PATCH] Some more doc comments

---
 src/imex/transfer.rs | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/src/imex/transfer.rs b/src/imex/transfer.rs
index 5e586354d..0e68a3969 100644
--- a/src/imex/transfer.rs
+++ b/src/imex/transfer.rs
@@ -362,7 +362,9 @@ fn spawn_progress_proxy(context: Context, mut rx: broadcast::Receiver<u16>) {
 enum ReceiveProgress {
     Connected,
     CollectionRecieved,
-    /// A value between 0 and 85 as percentage
+    /// A value between 0 and 85 interpreted as a percentage.
+    ///
+    /// Other values are already used by the other variants of this enum.
     BlobProgress(u16),
     Completed,
     Failed,
@@ -381,6 +383,15 @@ impl From<ReceiveProgress> for EventType {
     }
 }
 
+/// A generic progress event emitter.
+///
+/// It is created with a total value to reach and at which increments progress should be
+/// emitted.  E.g. when downloading a file of any size but you want percentage increments
+/// you would create `ProgressEmitter::new(file_size_in_bytes, 100)` and
+/// [`ProgressEmitter::subscribe`] will yield numbers `1..100` only.
+///
+/// Progress is made by calling [`ProgressEmitter::inc`], which can be implicitly done by
+/// [`ProgressEmitter::wrap_async_read`].
 #[derive(Debug, Clone)]
 struct ProgressEmitter {
     inner: Arc<InnerProgressEmitter>,
@@ -409,7 +420,7 @@ impl ProgressEmitter {
         self.inner.set_total(value)
     }
 
-    /// Return a receiver that gets incremental values.
+    /// Returns a receiver that gets incremental values.
     ///
     /// The values yielded depend on *steps* passed to [`ProgressEmitter::new`]: it will go
     /// from `1..steps`.
@@ -422,6 +433,7 @@ impl ProgressEmitter {
         self.inner.inc(amount);
     }
 
+    /// Wraps an [`AsyncRead`] which implicitly calls [`ProgressEmitter::inc`].
     fn wrap_async_read<R: AsyncRead + Unpin>(&self, read: R) -> ProgressAsyncReader<R> {
         ProgressAsyncReader {
             emitter: self.clone(),
@@ -460,6 +472,10 @@ impl InnerProgressEmitter {
     }
 }
 
+/// A wrapper around [`AsyncRead`] which increments a [`ProgressEmitter`].
+///
+/// This can be used just like the underlying [`AsyncRead`] but increments progress for each
+/// byte read.  Create this using [`ProgressEmitter::wrap_async_read`].
 #[derive(Debug)]
 struct ProgressAsyncReader<R: AsyncRead + Unpin> {
     emitter: ProgressEmitter,