From c7a0775b6181f9c40be91e5b9dec0fa5468cd8a4 Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Sat, 13 Apr 2024 20:34:40 -0700 Subject: [PATCH] docs: unify docs for callback types and functions that set callbacks This was motivated by the observations that: - The `PushNegotiation` docstring was previously much more informative than the docstring for `push_negotiation`. - The `PushNegotiation` docstring does not seem to be accessible via https://docs.rs/git2/0.18.3/git2/index.html. Only the less helpful docstring is accessible at https://docs.rs/git2/0.18.3/git2/struct.RemoteCallbacks.html#method.push_negotiation. --- src/remote_callbacks.rs | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/src/remote_callbacks.rs b/src/remote_callbacks.rs index 1169420bda..ade11bd471 100644 --- a/src/remote_callbacks.rs +++ b/src/remote_callbacks.rs @@ -83,13 +83,16 @@ 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 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(&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(&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(&mut self, cb: F) -> &mut RemoteCallbacks<'a> where F: FnMut(&[PushUpdate<'_>]) -> Result<(), Error> + 'a,