fix!: adjust the structure of commit::ancestors to be more consistent with other plumbing crates.

This makes sure that each time is reached by only a single path.

Author: Byron

gix-traverse/src/commit/ancestors.rs

@@ -4,54 +4,6 @@ use gix_hashtable::HashSet;
 use smallvec::SmallVec;
 use std::collections::VecDeque;
 
-/// Specify how to sort commits during traversal.
-///
-/// ### Sample History
-///
-/// The following history will be referred to for explaining how the sort order works, with the number denoting the commit timestamp
-/// (*their X-alignment doesn't matter*).
-///
-/// ```text
-/// ---1----2----4----7 <- second parent of 8
-///     \              \
-///      3----5----6----8---
-/// ```
-
-#[derive(Default, Debug, Copy, Clone)]
-pub enum Sorting {
-    /// Commits are sorted as they are mentioned in the commit graph.
-    ///
-    /// In the *sample history* the order would be `8, 6, 7, 5, 4, 3, 2, 1`
-    ///
-    /// ### Note
-    ///
-    /// This is not to be confused with `git log/rev-list --topo-order`, which is notably different from
-    /// as it avoids overlapping branches.
-    #[default]
-    BreadthFirst,
-    /// Commits are sorted by their commit time in descending order, that is newest first.
-    ///
-    /// The sorting applies to all currently queued commit ids and thus is full.
-    ///
-    /// In the *sample history* the order would be `8, 7, 6, 5, 4, 3, 2, 1`
-    ///
-    /// # Performance
-    ///
-    /// This mode benefits greatly from having an object_cache in `find()`
-    /// to avoid having to lookup each commit twice.
-    ByCommitTimeNewestFirst,
-    /// This sorting is similar to `ByCommitTimeNewestFirst`, but adds a cutoff to not return commits older than
-    /// a given time, stopping the iteration once no younger commits is queued to be traversed.
-    ///
-    /// As the query is usually repeated with different cutoff dates, this search mode benefits greatly from an object cache.
-    ///
-    /// In the *sample history* and a cut-off date of 4, the returned list of commits would be `8, 7, 6, 4`
-    ByCommitTimeNewestFirstCutoffOlderThan {
-        /// The amount of seconds since unix epoch, the same value obtained by any `gix_date::Time` structure and the way git counts time.
-        seconds: gix_date::SecondsSinceUnixEpoch,
-    },
-}
-
 /// The error is part of the item returned by the [Ancestors](super::Ancestors) iterator.
 #[derive(Debug, thiserror::Error)]
 #[allow(missing_docs)]
@@ -81,8 +33,8 @@ mod init {
     use gix_object::{CommitRefIter, FindExt};
 
     use super::{
-        super::{Ancestors, Either, Info, ParentIds, Parents},
-        collect_parents, Error, Sorting, State,
+        super::{Ancestors, Either, Info, ParentIds, Parents, Sorting},
+        collect_parents, Error, State,
     };
 
     impl Default for State {

gix-traverse/src/commit/mod.rs

@@ -1,7 +1,7 @@
 use gix_object::FindExt;
 use smallvec::SmallVec;
 
-/// An iterator over the ancestors one or more starting commits
+/// A fast iterator over the ancestors of one or more starting commits.
 pub struct Ancestors<Find, Predicate> {
     objects: Find,
     cache: Option<gix_commitgraph::Graph>,
@@ -11,9 +11,55 @@ pub struct Ancestors<Find, Predicate> {
     sorting: Sorting,
 }
 
+/// Specify how to sort commits during the [ancestor](Ancestors) traversal.
+///
+/// ### Sample History
+///
+/// The following history will be referred to for explaining how the sort order works, with the number denoting the commit timestamp
+/// (*their X-alignment doesn't matter*).
+///
+/// ```text
+/// ---1----2----4----7 <- second parent of 8
+///     \              \
+///      3----5----6----8---
+/// ```
+#[derive(Default, Debug, Copy, Clone)]
+pub enum Sorting {
+    /// Commits are sorted as they are mentioned in the commit graph.
+    ///
+    /// In the *sample history* the order would be `8, 6, 7, 5, 4, 3, 2, 1`
+    ///
+    /// ### Note
+    ///
+    /// This is not to be confused with `git log/rev-list --topo-order`, which is notably different from
+    /// as it avoids overlapping branches.
+    #[default]
+    BreadthFirst,
+    /// Commits are sorted by their commit time in descending order, that is newest first.
+    ///
+    /// The sorting applies to all currently queued commit ids and thus is full.
+    ///
+    /// In the *sample history* the order would be `8, 7, 6, 5, 4, 3, 2, 1`
+    ///
+    /// # Performance
+    ///
+    /// This mode benefits greatly from having an object_cache in `find()`
+    /// to avoid having to lookup each commit twice.
+    ByCommitTimeNewestFirst,
+    /// This sorting is similar to `ByCommitTimeNewestFirst`, but adds a cutoff to not return commits older than
+    /// a given time, stopping the iteration once no younger commits is queued to be traversed.
+    ///
+    /// As the query is usually repeated with different cutoff dates, this search mode benefits greatly from an object cache.
+    ///
+    /// In the *sample history* and a cut-off date of 4, the returned list of commits would be `8, 7, 6, 4`
+    ByCommitTimeNewestFirstCutoffOlderThan {
+        /// The amount of seconds since unix epoch, the same value obtained by any `gix_date::Time` structure and the way git counts time.
+        seconds: gix_date::SecondsSinceUnixEpoch,
+    },
+}
+
 /// Simple ancestors traversal
 pub mod ancestors;
-pub use ancestors::Sorting;
 
 // Topological traversal
 pub mod topo;

gix-traverse/src/commit/topo/mod.rs

@@ -60,16 +60,28 @@ bitflags! {
     }
 }
 
-/// Sorting to use for the topological walk
+/// Sorting to use for the topological walk.
+///
+/// ### Sample History
+///
+/// The following history will be referred to for explaining how the sort order works, with the number denoting the commit timestamp
+/// (*their X-alignment doesn't matter*).
+///
+/// ```text
+/// ---1----2----4----7 <- second parent of 8
+///     \              \
+///      3----5----6----8---
+/// ```
 #[derive(Clone, Copy, Debug, Default)]
 pub enum Sorting {
     /// Show no parents before all of its children are shown, but otherwise show
     /// commits in the commit timestamp order.
     #[default]
     DateOrder,
-
     /// Show no parents before all of its children are shown, and avoid
     /// showing commits on multiple lines of history intermixed.
+    ///
+    /// In the *sample history* the order would be `8, 6, 5, 3, 7, 4, 2, 1`
     TopoOrder,
 }