From ce466d152a5381aec11f9ba6a6fabf7f2ed1c8ad Mon Sep 17 00:00:00 2001 From: Kae Sluder Date: Sat, 13 Apr 2024 21:29:13 -0400 Subject: [PATCH 1/2] extend documentation for descendants and traverse original traverse documentation is a shortened version of descendants documentation. Edited documentation comments to clarify the following: 1. traverse and reverse_traverse return an iterator of `NodeEdge` objects. `NodeEdge` objects mark start (similar to `
`) and end (similar to `
`) of each node. 2. descendants returns an iterator of `Node` objects. This is probably more useful if you want to play with the Node contents. 3. added a short "Similar Functions" section to the inline documentation to point users in the right direction. --- src/arena_tree.rs | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/src/arena_tree.rs b/src/arena_tree.rs index f4fabd9b..5474911c 100644 --- a/src/arena_tree.rs +++ b/src/arena_tree.rs @@ -136,15 +136,23 @@ impl<'a, T> Node<'a, T> { ReverseChildren(self.last_child.get()) } - /// Return an iterator of references to this node and its descendants, in tree order. + /// Return an iterator of references to this `Node` and its descendants, in tree order. /// /// Parent nodes appear before the descendants. /// Call `.next().unwrap()` once on the iterator to skip the node itself. + /// + /// *Similar Functions:* Use `traverse()` or `reverse_traverse` if you need + /// references to the `NodeEdge` structs associated with each `AstNode` pub fn descendants(&'a self) -> Descendants<'a, T> { Descendants(self.traverse()) } - /// Return an iterator of references to this node and its descendants, in tree order. + /// Return an iterator of references to `NodeEdge` structs for each `Node` and its descendants, + /// in tree order. + /// + /// `NodeEdge` structs represent the `Start` and `End` of each node. + /// + /// *Similar Functions:* Use `descendants()` if you don't need `Start` and `End`. pub fn traverse(&'a self) -> Traverse<'a, T> { Traverse { root: self, @@ -152,7 +160,12 @@ impl<'a, T> Node<'a, T> { } } - /// Return an iterator of references to this node and its descendants, in tree order. + /// Return an iterator of references to `NodeEdge` structs for each `Node` and its descendants, + /// in *reverse* order. + /// + /// `NodeEdge` structs represent the `Start` and `End` of each node. + /// + /// *Similar Functions:* Use `descendants()` if you don't need `Start` and `End`. pub fn reverse_traverse(&'a self) -> ReverseTraverse<'a, T> { ReverseTraverse { root: self, From 209a4a8697a9a4dbda673647d4dcbf44472d957f Mon Sep 17 00:00:00 2001 From: Kae Sluder Date: Sat, 13 Apr 2024 21:37:32 -0400 Subject: [PATCH 2/2] minor fixes regarding vocabulary --- src/arena_tree.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/arena_tree.rs b/src/arena_tree.rs index 5474911c..72547460 100644 --- a/src/arena_tree.rs +++ b/src/arena_tree.rs @@ -142,15 +142,15 @@ impl<'a, T> Node<'a, T> { /// Call `.next().unwrap()` once on the iterator to skip the node itself. /// /// *Similar Functions:* Use `traverse()` or `reverse_traverse` if you need - /// references to the `NodeEdge` structs associated with each `AstNode` + /// references to the `NodeEdge` structs associated with each `Node` pub fn descendants(&'a self) -> Descendants<'a, T> { Descendants(self.traverse()) } - /// Return an iterator of references to `NodeEdge` structs for each `Node` and its descendants, + /// Return an iterator of references to `NodeEdge` enums for each `Node` and its descendants, /// in tree order. /// - /// `NodeEdge` structs represent the `Start` and `End` of each node. + /// `NodeEdge` enums represent the `Start` or `End` of each node. /// /// *Similar Functions:* Use `descendants()` if you don't need `Start` and `End`. pub fn traverse(&'a self) -> Traverse<'a, T> { @@ -160,10 +160,10 @@ impl<'a, T> Node<'a, T> { } } - /// Return an iterator of references to `NodeEdge` structs for each `Node` and its descendants, + /// Return an iterator of references to `NodeEdge` enums for each `Node` and its descendants, /// in *reverse* order. /// - /// `NodeEdge` structs represent the `Start` and `End` of each node. + /// `NodeEdge` enums represent the `Start` or `End` of each node. /// /// *Similar Functions:* Use `descendants()` if you don't need `Start` and `End`. pub fn reverse_traverse(&'a self) -> ReverseTraverse<'a, T> {