[repository #164] docs for easy::reference::log

git-repository/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 - Change return value of `prelude::RepositoryAccessExt::committer()` from `git_actor::Signature` to `Result<git_actor::Signature, easy::borrow:repo::Error>`
 - Change return value of `prelude::ReferenceAccessExt` from `Result<Vec<RefEdit>>, _>` to `Result<easy::Reference, _>`.
+- Rename `State` structs that serve as platform for iterators or other dependent types into `Platform`. These are usually intermediate objects only.
 
 ### v0.9.1 (2021-09-10)
 

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

@@ -4,7 +4,7 @@ use std::cell::Ref;
 use crate::easy;
 
 /// A platform to create iterators over references.
-#[must_use]
+#[must_use = "Iterators should be obtained from this iterator platform"]
 pub struct State<'r, A>
 where
     A: easy::Access + Sized,

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

@@ -1,11 +1,12 @@
-#![allow(missing_docs)]
+//!
 use std::{borrow::Borrow, cell::RefMut, marker::PhantomData, ops::DerefMut};
 
 use git_ref::file::ReferenceExt;
 
 use crate::{easy, easy::Reference};
 
-#[must_use = "Iterators should be obtained from this log buffer"]
+/// A platform to obtain iterators over reference logs.
+#[must_use = "Iterators should be obtained from this log platform"]
 pub struct State<'repo, A: 'repo, R>
 where
     R: Borrow<Reference<'repo, A>>,
@@ -15,23 +16,36 @@ where
     pub(crate) _phantom: PhantomData<A>,
 }
 
-#[derive(Debug, thiserror::Error)]
-pub enum Error {
-    #[error(transparent)]
-    Io(#[from] std::io::Error),
-    #[error(transparent)]
-    BorrowRepo(#[from] easy::borrow::repo::Error),
+///
+pub mod init {
+    use crate::easy;
+
+    /// The error returned by [State::iter()][super::State::iter()] and [State::iter_rev()][super::State::iter_rev()].
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error(transparent)]
+        Io(#[from] std::io::Error),
+        #[error(transparent)]
+        BorrowRepo(#[from] easy::borrow::repo::Error),
+    }
 }
 
+// TODO: use attached types with `access`
+/// An iterator over reference logs, most recent to oldest.
 pub type ReverseIter<'a> = git_ref::file::log::iter::Reverse<'a, std::fs::File>;
+/// An iterator over reference logs, oldest to newest.
 pub type ForwardIter<'a> = git_ref::file::log::iter::Forward<'a>;
 
 impl<'repo, A, R> State<'repo, A, R>
 where
     A: easy::Access + Sized,
     R: Borrow<Reference<'repo, A>>,
 {
-    pub fn iter_rev(&mut self) -> Result<Option<ReverseIter<'_>>, Error> {
+    /// Return a reverse iterator over reference logs, most recent to oldest.
+    ///
+    /// This is a typical and efficient way of accessing logs as one is interested in the most recent ones first.
+    pub fn iter_rev(&mut self) -> Result<Option<ReverseIter<'_>>, init::Error> {
         let buf = self.buf.deref_mut();
         buf.resize(512, 0);
         Ok(self
@@ -42,7 +56,11 @@ where
     }
 
     // TODO: tests
-    pub fn iter(&mut self) -> Result<Option<ForwardIter<'_>>, Error> {
+    /// Return an iterator over reference logs, from oldest to newest.
+    ///
+    /// The iterator is optimized for rewriting the processing or rewriting the entire log.
+    /// For accessing only the most recent entries, see [`iter_rev()`][State::iter_rev()].
+    pub fn iter(&mut self) -> Result<Option<ForwardIter<'_>>, init::Error> {
         let buf = self.buf.deref_mut();
         Ok(self
             .reference
@@ -56,6 +74,7 @@ impl<'repo, A> Reference<'repo, A>
 where
     A: easy::Access + Sized,
 {
+    /// Return a platform for obtaining iterators over reference logs.
     pub fn log(&self) -> Result<State<'repo, A, &'_ Reference<'repo, A>>, easy::borrow::state::Error> {
         Ok(State {
             reference: self,