Merge pull request #1044 from ilyagr/docs

Improve docs for PushUpdate, push_negotiation, plus a bit more

Author: ehuss

src/push_update.rs

@@ -28,17 +28,17 @@ impl PushUpdate<'_> {
         unsafe { crate::opt_bytes(self, (*self.raw).src_refname).unwrap() }
     }
 
-    /// Returns the source name of the reference.
+    /// Returns the source name of the reference, or None if it is not valid UTF-8.
     pub fn src_refname(&self) -> Option<&str> {
         str::from_utf8(self.src_refname_bytes()).ok()
     }
 
-    /// Returns the destination name of the reference as a byte slice.
+    /// Returns the name of the reference to update on the server as a byte slice.
     pub fn dst_refname_bytes(&self) -> &[u8] {
         unsafe { crate::opt_bytes(self, (*self.raw).dst_refname).unwrap() }
     }
 
-    /// Returns the destination name of the reference.
+    /// Returns the name of the reference to update on the server, or None if it is not valid UTF-8.
     pub fn dst_refname(&self) -> Option<&str> {
         str::from_utf8(self.dst_refname_bytes()).ok()
     }

src/remote_callbacks.rs

@@ -76,20 +76,23 @@ pub type PushUpdateReference<'a> = dyn FnMut(&str, Option<&str>) -> Result<(), E
 /// Callback for push transfer progress
 ///
 /// Parameters:
-///     * current
-///     * total
-///     * bytes
+/// * current
+/// * total
+/// * bytes
 pub type PushTransferProgress<'a> = dyn FnMut(usize, usize, usize) + 'a;
 
 /// Callback for pack progress
 ///
+/// Be aware that this is called inline with pack building operations,
+/// so performance may be affected.
+///
 /// Parameters:
-///     * stage
-///     * current
-///     * total
+/// * stage
+/// * current
+/// * total
 pub type PackProgress<'a> = dyn FnMut(PackBuilderStage, usize, usize) + 'a;
 
-/// Callback used to inform of upcoming updates.
+/// The callback is called once between the negotiation step and the upload.
 ///
 /// The argument is a slice containing the updates which will be sent as
 /// commands to the destination.
@@ -204,6 +207,11 @@ impl<'a> RemoteCallbacks<'a> {
     }
 
     /// The callback through which progress of push transfer is monitored
+    ///
+    /// Parameters:
+    /// * current
+    /// * total
+    /// * bytes
     pub fn push_transfer_progress<F>(&mut self, cb: F) -> &mut RemoteCallbacks<'a>
     where
         F: FnMut(usize, usize, usize) + 'a,
@@ -213,8 +221,14 @@ impl<'a> RemoteCallbacks<'a> {
     }
 
     /// Function to call with progress information during pack building.
+    ///
     /// Be aware that this is called inline with pack building operations,
     /// so performance may be affected.
+    ///
+    /// Parameters:
+    /// * stage
+    /// * current
+    /// * total
     pub fn pack_progress<F>(&mut self, cb: F) -> &mut RemoteCallbacks<'a>
     where
         F: FnMut(PackBuilderStage, usize, usize) + 'a,
@@ -224,7 +238,11 @@ impl<'a> RemoteCallbacks<'a> {
     }
 
     /// The callback is called once between the negotiation step and the upload.
-    /// It provides information about what updates will be performed.
+    ///
+    /// The argument to the callback is a slice containing the updates which
+    /// will be sent as commands to the destination.
+    ///
+    /// The push is cancelled if the callback returns an error.
     pub fn push_negotiation<F>(&mut self, cb: F) -> &mut RemoteCallbacks<'a>
     where
         F: FnMut(&[PushUpdate<'_>]) -> Result<(), Error> + 'a,