[repository #164] docs for top-level of easy::reference

git-repository/src/easy/ext/reference.rs

@@ -94,10 +94,10 @@ pub trait ReferenceAccessExt: easy::Access + Sized {
         target: impl Into<ObjectId>,
         constraint: PreviousValue,
         log_message: impl Into<BString>,
-    ) -> Result<Reference<'_, Self>, reference::create::Error>
+    ) -> Result<Reference<'_, Self>, reference::edit::Error>
     where
         Name: TryInto<FullName, Error = E>,
-        reference::create::Error: From<E>,
+        reference::edit::Error: From<E>,
     {
         let name = name.try_into()?;
         let id = target.into();

git-repository/src/easy/reference/log.rs

@@ -1,3 +1,4 @@
+#![allow(missing_docs)]
 use std::{borrow::Borrow, cell::RefMut, marker::PhantomData, ops::DerefMut};
 
 use git_ref::file::ReferenceExt;

git-repository/src/easy/reference/mod.rs

@@ -1,4 +1,4 @@
-#![allow(missing_docs)]
+//!
 use std::ops::DerefMut;
 
 use git_odb::Find;
@@ -11,82 +11,18 @@ use crate::{
 
 pub mod iter;
 
-pub mod namespace {
-    pub mod set {
-        use crate::easy;
-
-        #[derive(Debug, thiserror::Error)]
-        pub enum Error {
-            #[error(transparent)]
-            BorrowRepoMut(#[from] easy::borrow::repo::Error),
-            #[error(transparent)]
-            NameValidation(#[from] git_validate::refname::Error),
-        }
-    }
-}
-
-pub mod create {
-    use crate::easy;
-
-    #[derive(Debug, thiserror::Error)]
-    pub enum Error {
-        #[error(transparent)]
-        Edit(#[from] easy::reference::edit::Error),
-        #[error(transparent)]
-        NameValidation(#[from] git_validate::reference::name::Error),
-    }
-}
-
-pub mod edit {
-    use crate::easy;
-
-    #[derive(Debug, thiserror::Error)]
-    pub enum Error {
-        #[error(transparent)]
-        FileTransactionPrepare(#[from] git_ref::file::transaction::prepare::Error),
-        #[error(transparent)]
-        FileTransactionCommit(#[from] git_ref::file::transaction::commit::Error),
-        #[error(transparent)]
-        NameValidation(#[from] git_validate::reference::name::Error),
-        #[error("BUG: The repository could not be borrowed")]
-        BorrowRepo(#[from] easy::borrow::repo::Error),
-    }
-}
-
-pub mod peel {
-    use crate::easy;
-
-    #[derive(Debug, thiserror::Error)]
-    pub enum Error {
-        #[error(transparent)]
-        PeelToId(#[from] git_ref::peel::to_id::Error),
-        #[error(transparent)]
-        PackedRefsOpen(#[from] git_ref::packed::buffer::open::Error),
-        #[error("BUG: Part of interior state could not be borrowed.")]
-        BorrowState(#[from] easy::borrow::state::Error),
-        #[error("BUG: The repository could not be borrowed")]
-        BorrowRepo(#[from] easy::borrow::repo::Error),
-    }
-
-    impl From<easy::reference::packed::Error> for Error {
-        fn from(err: easy::reference::packed::Error) -> Self {
-            match err {
-                easy::reference::packed::Error::PackedRefsOpen(err) => Error::PackedRefsOpen(err),
-                easy::reference::packed::Error::BorrowState(err) => Error::BorrowState(err),
-            }
-        }
-    }
-}
-
 impl<'repo, A> Reference<'repo, A> {
+    /// Return the target to which this reference points to.
     pub fn target(&self) -> git_ref::TargetRef<'_> {
         self.inner.target.to_ref()
     }
 
+    /// Return the reference's full name.
     pub fn name(&self) -> git_ref::FullNameRef<'_> {
         self.inner.name.to_ref()
     }
 
+    /// Turn this instances into a stand-alone reference.
     pub fn detach(self) -> git_ref::Reference {
         self.inner
     }
@@ -103,6 +39,10 @@ where
         }
     }
 
+    /// Follow all symbolic targets this reference might point to and peel the underlying object
+    /// to the end of the chain, and return it.
+    ///
+    /// This is useful to learn where this reference is ulitmately pointing to.
     pub fn peel_to_id_in_place(&mut self) -> Result<Oid<'repo, A>, peel::Error> {
         let repo = self.access.repo()?;
         let state = self.access.state();
@@ -119,101 +59,104 @@ where
         Ok(Oid::from_id(oid, self.access))
     }
 
+    /// 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<Oid<'repo, A>, peel::Error> {
         self.peel_to_id_in_place()
     }
 }
 
-pub mod log;
+///
+pub mod namespace {
+    ///
+    pub mod set {
+        use crate::easy;
 
-pub(crate) mod packed {
-    use std::{
-        cell::{BorrowError, BorrowMutError},
-        time::SystemTime,
-    };
+        /// The error returned by [ReferenceAccessExt::set_namespace(…)][easy::ext::ReferenceAccessExt::set_namespace()].
+        #[derive(Debug, thiserror::Error)]
+        #[allow(missing_docs)]
+        pub enum Error {
+            #[error(transparent)]
+            BorrowRepoMut(#[from] easy::borrow::repo::Error),
+            #[error(transparent)]
+            NameValidation(#[from] git_validate::refname::Error),
+        }
+    }
+}
 
-    use git_ref::file;
+///
+pub mod edit {
+    use crate::easy;
 
+    /// The error returned by [ReferenceAccessExt::edit_references(…)][easy::ext::ReferenceAccessExt::edit_references()], and others
+    /// which ultimately create a reference.
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        FileTransactionPrepare(#[from] git_ref::file::transaction::prepare::Error),
+        #[error(transparent)]
+        FileTransactionCommit(#[from] git_ref::file::transaction::commit::Error),
+        #[error(transparent)]
+        NameValidation(#[from] git_validate::reference::name::Error),
+        #[error("BUG: The repository could not be borrowed")]
+        BorrowRepo(#[from] easy::borrow::repo::Error),
+    }
+}
+
+///
+pub mod peel {
     use crate::easy;
 
+    /// The error returned by [Reference::peel_to_id_in_place(…)][easy::Reference::peel_to_id_in_place()] and
+    /// [Reference::into_fully_peeled_id(…)][easy::Reference::into_fully_peeled_id()].
     #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
     pub enum Error {
+        #[error(transparent)]
+        PeelToId(#[from] git_ref::peel::to_id::Error),
         #[error(transparent)]
         PackedRefsOpen(#[from] git_ref::packed::buffer::open::Error),
         #[error("BUG: Part of interior state could not be borrowed.")]
         BorrowState(#[from] easy::borrow::state::Error),
+        #[error("BUG: The repository could not be borrowed")]
+        BorrowRepo(#[from] easy::borrow::repo::Error),
     }
 
-    impl From<std::cell::BorrowError> for Error {
-        fn from(err: BorrowError) -> Self {
-            Error::BorrowState(easy::borrow::state::Error::Borrow(err))
-        }
-    }
-    impl From<std::cell::BorrowMutError> for Error {
-        fn from(err: BorrowMutError) -> Self {
-            Error::BorrowState(easy::borrow::state::Error::BorrowMut(err))
-        }
-    }
-
-    #[derive(Default)]
-    pub(crate) struct ModifieablePackedRefsBuffer {
-        pub(crate) packed_refs: Option<git_ref::packed::Buffer>,
-        modified: Option<SystemTime>,
-    }
-
-    impl ModifieablePackedRefsBuffer {
-        pub fn assure_packed_refs_uptodate(
-            &mut self,
-            file: &file::Store,
-        ) -> Result<(), git_ref::packed::buffer::open::Error> {
-            let packed_refs_modified_time = || file.packed_refs_path().metadata().and_then(|m| m.modified()).ok();
-            if self.packed_refs.is_none() {
-                self.packed_refs = file.packed_buffer()?;
-                if self.packed_refs.is_some() {
-                    self.modified = packed_refs_modified_time();
-                }
-            } else {
-                let recent_modification = packed_refs_modified_time();
-                match (&self.modified, recent_modification) {
-                    (None, None) => {}
-                    (Some(_), None) => {
-                        self.packed_refs = None;
-                        self.modified = None
-                    }
-                    (Some(cached_time), Some(modified_time)) => {
-                        if *cached_time < modified_time {
-                            self.packed_refs = file.packed_buffer()?;
-                            self.modified = Some(modified_time);
-                        }
-                    }
-                    (None, Some(modified_time)) => {
-                        self.packed_refs = file.packed_buffer()?;
-                        self.modified = Some(modified_time);
-                    }
-                }
+    impl From<easy::reference::packed::Error> for Error {
+        fn from(err: easy::reference::packed::Error) -> Self {
+            match err {
+                easy::reference::packed::Error::PackedRefsOpen(err) => Error::PackedRefsOpen(err),
+                easy::reference::packed::Error::BorrowState(err) => Error::BorrowState(err),
             }
-            Ok(())
         }
     }
 }
 
+pub mod log;
+pub(crate) mod packed;
+
+///
 pub mod find {
     use crate::easy;
 
+    ///
     pub mod existing {
+        use crate::easy;
 
-        use crate::easy::reference::find;
-
+        /// The error returned by [ReferenceAccessExt::find_reference(…)][easy::ext::ReferenceAccessExt::find_reference()], and others.
         #[derive(Debug, thiserror::Error)]
+        #[allow(missing_docs)]
         pub enum Error {
             #[error(transparent)]
-            Find(#[from] find::Error),
+            Find(#[from] easy::reference::find::Error),
             #[error("The reference did not exist even though that was expected")]
             NotFound,
         }
     }
 
+    /// The error returned by [ReferenceAccessExt::try_find_reference(…)][easy::ext::ReferenceAccessExt::try_find_reference()].
     #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
     pub enum Error {
         #[error(transparent)]
         Find(#[from] git_ref::file::find::Error),

git-repository/src/easy/reference/packed.rs

@@ -0,0 +1,69 @@
+use std::{
+    cell::{BorrowError, BorrowMutError},
+    time::SystemTime,
+};
+
+use git_ref::file;
+
+use crate::easy;
+
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    #[error(transparent)]
+    PackedRefsOpen(#[from] git_ref::packed::buffer::open::Error),
+    #[error("BUG: Part of interior state could not be borrowed.")]
+    BorrowState(#[from] easy::borrow::state::Error),
+}
+
+impl From<std::cell::BorrowError> for Error {
+    fn from(err: BorrowError) -> Self {
+        Error::BorrowState(easy::borrow::state::Error::Borrow(err))
+    }
+}
+
+impl From<std::cell::BorrowMutError> for Error {
+    fn from(err: BorrowMutError) -> Self {
+        Error::BorrowState(easy::borrow::state::Error::BorrowMut(err))
+    }
+}
+
+#[derive(Default)]
+pub(crate) struct ModifieablePackedRefsBuffer {
+    pub(crate) packed_refs: Option<git_ref::packed::Buffer>,
+    modified: Option<SystemTime>,
+}
+
+impl ModifieablePackedRefsBuffer {
+    pub fn assure_packed_refs_uptodate(
+        &mut self,
+        file: &file::Store,
+    ) -> Result<(), git_ref::packed::buffer::open::Error> {
+        let packed_refs_modified_time = || file.packed_refs_path().metadata().and_then(|m| m.modified()).ok();
+        if self.packed_refs.is_none() {
+            self.packed_refs = file.packed_buffer()?;
+            if self.packed_refs.is_some() {
+                self.modified = packed_refs_modified_time();
+            }
+        } else {
+            let recent_modification = packed_refs_modified_time();
+            match (&self.modified, recent_modification) {
+                (None, None) => {}
+                (Some(_), None) => {
+                    self.packed_refs = None;
+                    self.modified = None
+                }
+                (Some(cached_time), Some(modified_time)) => {
+                    if *cached_time < modified_time {
+                        self.packed_refs = file.packed_buffer()?;
+                        self.modified = Some(modified_time);
+                    }
+                }
+                (None, Some(modified_time)) => {
+                    self.packed_refs = file.packed_buffer()?;
+                    self.modified = Some(modified_time);
+                }
+            }
+        }
+        Ok(())
+    }
+}

git-repository/src/easy/state.rs

@@ -1,4 +1,4 @@
-#![allow(missing_docs)]
+//!
 use std::cell::{Ref, RefMut};
 
 use git_ref::file;