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.

[`PushNegotiation` docstring]: 920c838#diff-ccd8cf48c67bd6cc71379f93a6b51abdb10954497a0db353908a7cf20995ef61R92-R99

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<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,