feat: Reference::TBD

Author: Byron

gix/src/reference/mod.rs

@@ -65,19 +65,21 @@ impl<'repo> Reference<'repo> {
 
 /// Peeling
 impl<'repo> Reference<'repo> {
-    /// Follow all symbolic targets this reference might point to and peel the underlying object
-    /// to the end of the chain, and return it.
+    /// Follow all symbolic targets this reference might point to and peel all annotated tags
+    /// to their first non-tag target, and return it,
     ///
-    /// This is useful to learn where this reference is ultimately pointing to.
+    /// This is useful to learn where this reference is ultimately pointing to after following
+    /// the chain of symbolic refs and annotated tags.
     pub fn peel_to_id_in_place(&mut self) -> Result<Id<'repo>, peel::Error> {
         let oid = self.inner.peel_to_id_in_place(&self.repo.refs, &self.repo.objects)?;
         Ok(Id::from_id(oid, self.repo))
     }
 
-    /// Follow all symbolic targets this reference might point to and peel the underlying object
-    /// to the end of the chain, and return it, reusing the `packed` buffer if available.
+    /// Follow all symbolic targets this reference might point to and peel all annotated tags
+    /// to their first non-tag target, and return it, reusing the `packed` buffer if available.
     ///
-    /// This is useful to learn where this reference is ultimately pointing to.
+    /// This is useful to learn where this reference is ultimately pointing to after following
+    /// the chain of symbolic refs and annotated tags.
     pub fn peel_to_id_in_place_packed(
         &mut self,
         packed: Option<&gix_ref::packed::Buffer>,
@@ -88,7 +90,7 @@ impl<'repo> Reference<'repo> {
         Ok(Id::from_id(oid, self.repo))
     }
 
-    /// Similar to [`peel_to_id_in_place()`][Reference::peel_to_id_in_place()], but consumes this instance.
+    /// Similar to [`peel_to_id_in_place()`](Reference::peel_to_id_in_place()), but consumes this instance.
     pub fn into_fully_peeled_id(mut self) -> Result<Id<'repo>, peel::Error> {
         self.peel_to_id_in_place()
     }