changed Base.values method to nodevalues; a bunch of new docs

Author: ExpandingMan

docs/src/index.md

@@ -87,9 +87,30 @@ NodeTypeUnknown
 HasNodeType
 ```
 
-This can be used e.g. to guarantee the `eltype` of `TreeIterator`s.  It should be defined especially
-for trees in which all nodes have the same type, which are the only cases in which iteration over a
-tree can be type stable.
+Providing the `HasNodeType` trait will guarantee that all nodes connected to the node must be of the
+type returned by [`nodetype`](@ref).
+
+An important use case of this trait is to guarantee the return types of a `TreeIterator`.  Tree
+nodes with `NodeTypeUnknown` cannot have type-stable iteration over the entire tree.
+
+For example
+```julia
+struct ExampleNode
+    x::Int
+    children::Vector{ExampleNode}
+end
+
+AbstractTrees.nodevalue(x::ExampleNode) = x.x
+AbstractTrees.children(x::ExampleNode) = x.children
+
+AbstractTrees.NodeType(::Type{<:ExampleNode}) = HasNodeType()
+AbstractTrees.nodetype(::Type{<:ExampleNode}) = ExampleNode
+```
+In this example, iteration over a tree of `ExampleNode`s is type-stable with `eltype`
+`ExampleNode`.
+
+Providing the `nodetype(::Type)` method is preferable to defining `nodetype(::ExampleNode)` because
+it ensures that `nodetype` can be involved at compile time even if values are not known.
 
 
 ## The Indexed Tree Interface
@@ -124,9 +145,25 @@ prevsiblingindex
 rootindex
 ```
 
+## Additional Functions
+```@docs
+getdescendant
+nodevalues
+ischild
+isroot
+intree
+isdescendant
+treebreadth
+treeheight
+descendleft
+getroot
+```
+
 ## Example Implementations
 - All objects in base which define the abstract trees interface are defined in
     [`builtins.jl`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/src/builtins.jl).
-- [`IDTree`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/idtree.jl)
-- [`OneNode`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/onenode.jl)
-- [`OneTree`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/onetree.jl)
+- [`IDTree`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/examples/idtree.jl)
+- [`OneNode`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/examples/onenode.jl)
+- [`OneTree`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/examples/onetree.jl)
+- [`FSNode`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/examples/fstree.jl)
+- [`BinaryNode`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/examples/binarytree.jl)

src/AbstractTrees.jl

@@ -25,7 +25,7 @@ export ParentLinks, StoredParents, ImplicitParents
 export SiblingLinks, StoredSiblings, ImplicitSiblings
 export ChildIndexing, IndexedChildren, NonIndexedChildren
 export NodeType, HasNodeType, NodeTypeUnknown
-export nodetype, nodevalue, children, parentlinks, siblinglinks, childindexing, childtype, childrentype
+export nodetype, nodevalue, nodevalues, children, parentlinks, siblinglinks, childindexing, childtype, childrentype
 #extended interface
 export nextsibling, prevsibling
 

src/iteration.jl

@@ -76,12 +76,12 @@ function Base.iterate(ti::TreeIterator, s::Union{Nothing,IteratorState}=initial(
 end
 
 """
-    values(itr::TreeIterator)
+    nodevalues(itr::TreeIterator)
 
 An iterator which returns the `nodevalue` of each node in the tree, equivalent to
 `Iterators.map(nodevalue, itr)`.
 """
-Base.values(itr::TreeIterator) = Iterators.map(nodevalue, itr)
+nodevalues(itr::TreeIterator) = Iterators.map(nodevalue, itr)
 
 """
     PreOrderState{T<:TreeCursor} <: IteratorState{T}

test/builtins.jl

@@ -80,7 +80,7 @@ end
     a = [1,[2,[3]]]
     f = n -> n isa AbstractArray ? (nothing, children(n)) : (n+1, children(n))
     b = treemap(f, a)
-    @test nodevalue.(PreOrderDFS(b)) == [nothing, 2, nothing, 3, nothing, 4]
+    @test collect(nodevalues(PreOrderDFS(b))) == [nothing, 2, nothing, 3, nothing, 4]
     g = n -> isempty(children(n)) ? (nodevalue(n), ()) : (nothing, [0; children(n)])
     b = treemap(g, a)
     @test nodevalue.(PostOrderDFS(b)) == [0, 1, 0, 2, 0, 3, nothing, nothing, nothing]