[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	5	/// Commit traversal
6	6	pub mod commit;
7	7
8		−///
	8	+/// Tree traversal
9	9	pub mod tree;

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

@@ -5,7 +5,7 @@ use quick_error::quick_error; · 4 unmodified lines
5	5	use std::{borrow::BorrowMut, collections::VecDeque};
6	6
7	7	quick_error! {
8		− /// The error is part of the item returned by the [breadthfirst] function.
	8	+ /// The error is part of the item returned by the [`traverse()`] function.
9	9	#[derive(Debug)]
10	10	#[allow(missing_docs)]
11	11	pub enum Error {
@@ -37,18 +37,19 @@ impl<PathId: Clone> State<PathId> { · 25 unmodified lines
37	37	}
38	38	}
39	39
40		−/// Create a new instance.
	40	+/// Start a breadth-first iteration over the `root` trees entries.
41	41	///
	42	+/// * `root`
	43	+/// * the starting points of the iteration
	44	+/// * each commit they lead to will only be returned once, including the tip that started it
	45	+/// * `state` - all state used for the iteration. If multiple iterations are performed, allocations can be minimized by reusing
	46	+/// this state.
42	47	/// * `find` - a way to lookup new object data during traversal by their ObjectId, writing their data into buffer and returning
43	48	/// an iterator over entries if the object is present and is a tree. Caching should be implemented within this function
44	49	/// as needed. The return value is `Option<TreeIter>` which degenerates all error information. Not finding a commit should also
45	50	/// be considered an errors as all objects in the tree DAG should be present in the database. Hence [`Error::NotFound`] should
46	51	/// be escalated into a more specific error if its encountered by the caller.
47		−/// * `state` - all state used for the iteration. If multiple iterations are performed, allocations can be minimized by reusing
48		−/// this state.
49		−/// * `root`
50		−/// * the starting points of the iteration
51		−/// * each commit they lead to will only be returned once, including the tip that started it
	52	+/// * `delegate` - A way to observe entries and control the iteration while allowing the optimizer to let you pay only for what you use.
52	53	pub fn traverse<StateMut, Find, V>(
53	54	root: impl Into<ObjectId>,
54	55	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	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	1	use git_hash::bstr::BStr;
2	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	5	#[derive(Clone, Copy, PartialOrd, PartialEq, Ord, Eq, Hash)]
6	6	pub enum Action {
7	7	/// Continue the traversal of entries.
8	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	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	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	22	.into_commit_iter()
23	23	.expect("commit present");
24	24	let mut recorder = tree::Recorder::default();
25		− tree::breadthfirst::traverse(
	25	+ git_traverse::tree::breadthfirst(
26	26	commit.tree_id().expect("a tree is available in a commit"),
27	27	tree::breadthfirst::State::default(),
28	28	\|oid, buf\| {