repository!: rename *::State into *::Platform(#164)

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

@@ -209,11 +209,11 @@ pub trait ReferenceAccessExt: easy::Access + Sized {
     ///
     /// Common kinds of iteration are [all][easy::reference::iter::State::all()] or [prefixed][easy::reference::iter::State::prefixed()]
     /// references.
-    fn references(&self) -> Result<easy::reference::iter::State<'_, Self>, easy::reference::iter::Error> {
+    fn references(&self) -> Result<easy::reference::iter::Platform<'_, Self>, easy::reference::iter::Error> {
         let state = self.state();
         let repo = self.repo()?;
         let packed_refs = state.assure_packed_refs_uptodate(&repo.refs)?;
-        Ok(easy::reference::iter::State {
+        Ok(easy::reference::iter::Platform {
             repo,
             packed_refs,
             access: self,

git-repository/src/easy/head.rs

@@ -84,8 +84,8 @@ pub mod log {
         A: easy::Access + Sized,
     {
         /// Return a platform for obtaining iterators on the reference log associated with the `HEAD` reference.
-        pub fn log(&self) -> Result<easy::reference::log::State<'repo, A, easy::Reference<'repo, A>>, Error> {
-            Ok(easy::reference::log::State {
+        pub fn log(&self) -> Result<easy::reference::log::Platform<'repo, A, easy::Reference<'repo, A>>, Error> {
+            Ok(easy::reference::log::Platform {
                 reference: self.access.find_reference("HEAD")?,
                 buf: self.access.state().try_borrow_mut_buf()?,
                 _phantom: PhantomData::default(),

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

@@ -5,7 +5,7 @@ use crate::easy;
 
 /// A platform to create iterators over references.
 #[must_use = "Iterators should be obtained from this iterator platform"]
-pub struct State<'r, A>
+pub struct Platform<'r, A>
 where
     A: easy::Access + Sized,
 {
@@ -20,7 +20,7 @@ pub struct Iter<'r, A> {
     access: &'r A,
 }
 
-impl<'r, A> State<'r, A>
+impl<'r, A> Platform<'r, A>
 where
     A: easy::Access + Sized,
 {

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

@@ -7,7 +7,7 @@ use crate::{easy, easy::Reference};
 
 /// 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>
+pub struct Platform<'repo, A: 'repo, R>
 where
     R: Borrow<Reference<'repo, A>>,
 {
@@ -37,7 +37,7 @@ 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>
+impl<'repo, A, R> Platform<'repo, A, R>
 where
     A: easy::Access + Sized,
     R: Borrow<Reference<'repo, A>>,
@@ -75,8 +75,8 @@ 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 {
+    pub fn log(&self) -> Result<Platform<'repo, A, &'_ Reference<'repo, A>>, easy::borrow::state::Error> {
+        Ok(Platform {
             reference: self,
             buf: self.access.state().try_borrow_mut_buf()?,
             _phantom: Default::default(),

git-repository/src/lib.rs

@@ -16,7 +16,8 @@
 //! Most extensions to existing objects provide an `obj_with_extension.easy(&repo).an_easier_version_of_a_method()` or `easy(&repo)`
 //! method to hide all complex arguments and sacrifice some performance for a lot of convenience.
 //!
-//! When starting out, use `easy(…)` and migrate to the more detailed method signatures to squeeze out more performance.
+//! When starting out, use `easy(…)` and migrate to the more detailed method signatures to squeeze out the last inkling of performance
+//! if it really does make a difference.
 //!
 //! ### Shortcomings & Limitations
 //!
@@ -46,6 +47,8 @@
 //!   However, other ways to adjust the `Repository` of long-running applications are possible. For instance, there could be a flag that
 //!   indicates a new `Repository` should be created (for instance, after it was changed) which causes the next server connection to
 //!   create a new one. This instance is the one to use when spawning new `EasyArc` instances.
+//! * `Platform` types are used to hold mutable or shared versions of required state for use in dependent objects they create, like iterators.
+//!   These come with the benefit of allowing for nicely readable call chains.
 //!
 //! ### Terminology
 //!