[traverse-tree] more proper docs

Sebastian Thiel committed 5 years ago

Commit f66ccd31 parent f7eb3555 files · +15 −12Browse files

Unified · Split

5 files

git-traverse/src/lib.rs +1 −1
git-traverse/src/tree/breadthfirst.rs +8 −7
git-traverse/src/tree/mod.rs +2 −0
git-traverse/src/tree/visit.rs +3 −3
git-traverse/tests/tree/mod.rs +1 −1

@@ -5,5 +5,5 @@ · 4 unmodified lines
5	/// Commit traversal	5	/// Commit traversal
6	pub mod commit;	6	pub mod commit;
7		7
8	///	8	/// Tree traversal
9	pub mod tree;	9	pub mod tree;

git-traverse/src/tree/breadthfirst.rs+8−7

 use std::{borrow::BorrowMut, collections::VecDeque};
 quick_error! {
-    /// The error is part of the item returned by the [breadthfirst] function.
+    /// The error is part of the item returned by the [`traverse()`] function.
     #[derive(Debug)]
     #[allow(missing_docs)]
     pub enum Error {
     }
 }
-/// Create a new instance.
+/// Start a breadth-first iteration over the `root` trees entries.
 ///
+/// * `root`
+///   * the starting points of the iteration
+///   * each commit they lead to will only be returned once, including the tip that started it
+/// * `state` - all state used for the iteration. If multiple iterations are performed, allocations can be minimized by reusing
+///   this state.
 /// * `find` - a way to lookup new object data during traversal by their ObjectId, writing their data into buffer and returning
 ///    an iterator over entries if the object is present and is a tree. Caching should be implemented within this function
 ///    as needed. The return value is `Option<TreeIter>` which degenerates all error information. Not finding a commit should also
 ///    be considered an errors as all objects in the tree DAG should be present in the database. Hence [`Error::NotFound`] should
 ///    be escalated into a more specific error if its encountered by the caller.
-/// * `state` - all state used for the iteration. If multiple iterations are performed, allocations can be minimized by reusing
+/// * `delegate` - A way to observe entries and control the iteration while allowing the optimizer to let you pay only for what you use.
-///   this state.
-/// * `root`
-///   * the starting points of the iteration
-///   * each commit they lead to will only be returned once, including the tip that started it
 pub fn traverse<StateMut, Find, V>(
     root: impl Into<ObjectId>,
     mut state: StateMut,

git-traverse/src/tree/mod.rs+2−0

@@ -8,3 +8,5 @@ pub use recorder::Recorder; · 7 unmodified lines
8		8
9	///	9	///
10	pub mod breadthfirst;	10	pub mod breadthfirst;
		11	#[doc(inline)]
		12	pub use breadthfirst::traverse as breadthfirst;

git-traverse/src/tree/visit.rs+3−3

@@ -1,14 +1,14 @@
1	use git_hash::bstr::BStr;	1	use git_hash::bstr::BStr;
2	use git_object::immutable;	2	use git_object::immutable;
3		3
4	/// What to do after an entry was [recorded][Visit::visit()].	4	/// What to do after an entry was [recorded][Visit::visit_tree()].
5	#[derive(Clone, Copy, PartialOrd, PartialEq, Ord, Eq, Hash)]	5	#[derive(Clone, Copy, PartialOrd, PartialEq, Ord, Eq, Hash)]
6	pub enum Action {	6	pub enum Action {
7	/// Continue the traversal of entries.	7	/// Continue the traversal of entries.
8	Continue,	8	Continue,
9	/// Stop the traversal of entries, making this te last call to [visit(…)][Visit::visit()].	9	/// Stop the traversal of entries, making this te last call to [`visit_(tree\|nontree)(…)`][Visit::visit_nontree()].
10	Cancel,	10	Cancel,
11	/// Don't dive into the entry, skipping children effectively.	11	/// Don't dive into the entry, skipping children effectively. Only useful in [`visit_tree(…)`][Visit::visit_tree()].
12	Skip,	12	Skip,
13	}	13	}
14		14

git-traverse/tests/tree/mod.rs+1−1

@@ -22,7 +22,7 @@ fn basic_nesting() -> crate::Result<()> { · 21 unmodified lines
22	.into_commit_iter()	22	.into_commit_iter()
23	.expect("commit present");	23	.expect("commit present");
24	let mut recorder = tree::Recorder::default();	24	let mut recorder = tree::Recorder::default();
25	tree::breadthfirst::traverse(	25	git_traverse::tree::breadthfirst(
26	commit.tree_id().expect("a tree is available in a commit"),	26	commit.tree_id().expect("a tree is available in a commit"),
27	tree::breadthfirst::State::default(),	27	tree::breadthfirst::State::default(),
28	\|oid, buf\| {	28	\|oid, buf\| {