improve documentation of PrepareCheckout and make it easier to use

Now it's clear why it does what it does with the internal
repository, even though admittedly it could also
be made so that it can be called multiple times (despite
making no sense).

Author: Byron

gix/src/clone/checkout.rs

@@ -65,6 +65,12 @@ pub mod main_worktree {
         ///
         /// Note that this is a no-op if the remote was empty, leaving this repository empty as well. This can be validated by checking
         /// if the `head()` of the returned repository is *not* unborn.
+        ///
+        /// # Panics
+        ///
+        /// If called after it was successful. The reason here is that it auto-deletes the contained repository,
+        /// and keeps track of this by means of keeping just one repository instance, which is passed to the user
+        /// after success.
         pub fn main_worktree<P>(
             &mut self,
             mut progress: P,
@@ -86,7 +92,7 @@ pub mod main_worktree {
             let repo = self
                 .repo
                 .as_ref()
-                .expect("still present as we never succeeded the worktree checkout yet");
+                .expect("BUG: this method may only be called until it is successful");
             let workdir = repo.work_dir().ok_or_else(|| Error::BareRepository {
                 git_dir: repo.git_dir().to_owned(),
             })?;
@@ -138,7 +144,7 @@ pub mod main_worktree {
             bytes.show_throughput(start);
 
             index.write(Default::default())?;
-            Ok((self.repo.take().expect("still present"), outcome))
+            Ok((self.repo.take().expect("still present").clone(), outcome))
         }
     }
 }

gix/src/clone/mod.rs

@@ -140,13 +140,13 @@ impl PrepareFetch {
     }
 }
 
-/// A utility to collect configuration on how to perform a checkout into a working tree, and when dropped without checking out successfully
-/// the fetched repository will be dropped.
+/// A utility to collect configuration on how to perform a checkout into a working tree,
+/// and when dropped without checking out successfully the fetched repository will be deleted from disk.
 #[must_use]
 #[cfg(feature = "worktree-mutation")]
 #[derive(Debug)]
 pub struct PrepareCheckout {
-    /// A freshly initialized repository which is owned by us, or `None` if it was handed to the user
+    /// A freshly initialized repository which is owned by us, or `None` if it was successfully checked out.
     pub(self) repo: Option<crate::Repository>,
     /// The name of the reference to check out. If `None`, the reference pointed to by `HEAD` will be checked out.
     pub(self) ref_name: Option<gix_ref::PartialName>,