some changes based on feedback from oscardssmith

Author: ExpandingMan

src/base.jl

@@ -44,19 +44,6 @@ the children from the node alone, this should be defined for a wrapper object wh
 """
 children(node) = ()
 
-"""
-    siblings(node)
-
-Get the siblings (i.e. children of the parent of) the node `node`.  The fall-back method for this only works for
-nodes with the trait [`StoredParents`](@ref).
-
-For a general case iterator see [`Siblings`](@ref).
-
-**OPTIONAL**: This function is optional in all cases.
-"""
-siblings(node) = siblings(ParentLinks(node), node)
-siblings(::StoredParents, node) = (children ∘ parent)(node)
-
 """
     nextsibling(node)
 
@@ -80,15 +67,15 @@ obtain the previous sibling and all iterators act in the "forward" direction.
 function prevsibling end
 
 """
-    ischild(node1, node2; equiv=(≡))
+    ischild(node1, node2; equiv=(===))
 
 Check if `node1` is a child of `node2`.
 
 By default this iterates through `children(node2)`, so performance may be improved by adding a
 specialized method for given node type.
 
 Equivalence is established with the `equiv` function.  New methods of this function should include this
-argument or else it will fall back to `≡`.
+argument or else it will fall back to `===`.
 """
 ischild(node1, node2; equiv=(≡)) = any(node -> equiv(node, node1), children(node2))
 
@@ -101,7 +88,7 @@ By default all objects are considered nodes of a trivial tree with no children a
 the default method is simply `parent(node) = nothing`.
 
 **OPTIONAL**: The 1-argument version of this function must be implemented for nodes with the [`StoredParents`](@ref)
-trait.  The 2-argument version is always optional.
+trait.
 """
 parent(node) = nothing
 

src/builtins.jl

@@ -9,4 +9,4 @@ ChildIndexing(::Expr) = IndexedChildren()
 children(p::Pair) = (p[2],)
 ChildIndexing(::Pair) = IndexedChildren()
 
-children(dct::AbstractDict) = pairs(dct)
+children(dict::AbstractDict) = pairs(dict)

src/cursors.jl

@@ -16,12 +16,13 @@ Abstract type for tree cursors which when constructed from a node can be used to
 navigate the entire tree descended from that node.
 
 Tree cursors satisfy the abstract tree interface with a few additional guarantees:
-- In addition to [`children`](@ref), [`parent`](@ref), [`nextsibling`](@ref) and
-    optionally [`prevsibling`](@ref) must be defined.
+- Tree cursors always define [`children`](@ref), [`parent`](@ref) and [`nextsibling`](@ref).
+    [`prevsibling`](@ref) may be defined depending on whether it is defined for the wrapped tree.
 - The above functions returning tree nodes are guaranteed to also return tree cursors.
 
 Tree nodes which define `children` and have the traits [`StoredParents`](@ref) and
-[`StoredSiblings`](@ref) satisfy the `TreeCursor` interface and can be used as such.
+[`StoredSiblings`](@ref) satisfy the `TreeCursor` interface, but calling `TreeCursor(node)` on such
+a node wraps them in a [`TrivialCursor`](@ref) to maintain a consistent interface.
 
 ## Constructors
 All `TreeCursor`s possess (at least) the following constructors

src/iteration.jl

@@ -116,7 +116,7 @@ function next(f, s::PreOrderState)
     end
     nothing
 end
-next(s::PreOrderState) = next(x -> true, s)
+next(s::PreOrderState) = next(_ -> true, s)
 
 
 """
@@ -146,7 +146,7 @@ struct PreOrderDFS{T,F} <: TreeIterator{T}
     root::T
 end
 
-PreOrderDFS(root) = PreOrderDFS(x -> true, root)
+PreOrderDFS(root) = PreOrderDFS(_ -> true, root)
 
 statetype(itr::PreOrderDFS) = PreOrderState
 
@@ -211,7 +211,7 @@ statetype(itr::PostOrderDFS) = PostOrderState
 """
     LeavesState{T<:TreeCursor} <: IteratorState{T}
 
-A [`IteratorState`](@ref) of an iterator which visits all and only the laves of a tree.
+A [`IteratorState`](@ref) of an iterator which visits the leaves of a tree.
 
 See [`Leaves`](@ref).
 """
@@ -366,7 +366,7 @@ end
 
 Base.iterate(ti::StatelessBFS) = (ti.root, [])
 
-function _descend_left(inds, next_node, lvl)
+function _level(inds, next_node, lvl)
     while length(inds) ≠ lvl
         ch = children(next_node)
         isempty(ch) && break
@@ -390,7 +390,7 @@ function _nextind_or_deadend(node, ind, lvl)
         if !isnothing(iterate(ch, ni))
             newinds = [active_inds; ni]
             next_node = ch[ni]
-            return _descend_left(newinds, next_node, lvl)
+            return _level(newinds, next_node, lvl)
         end
     end
     nothing
@@ -404,7 +404,7 @@ function Base.iterate(ti::StatelessBFS, ind)
         if isnothing(newinds)
             active_lvl += 1
             active_lvl > org_lvl + 1 && return nothing
-            newinds = _descend_left([], ti.root, active_lvl)
+            newinds = _level([], ti.root, active_lvl)
         end
         length(newinds) == active_lvl && break
     end
@@ -416,7 +416,7 @@ end
 """
     MapNode{T,C}
 
-A node in a tree which is returned by [`treemap`](@ref).  It consists of a value which is hte result of the function
+A node in a tree which is returned by [`treemap`](@ref).  It consists of a value which is the result of the function
 call and an array of the children, which are also of type `MapNode`.
 
 Every `MapNode` is itself a tree with the [`IndexedChildren`](@ref) trait and therefore supports indexing via
@@ -454,29 +454,29 @@ Base.show(io::IO, ::MIME"text/plain", μ::MapNode) = print_tree(io, μ)
 
 #TODO: still experimenting here
 """
-    treemap(𝒻, node)
+    treemap(f, node)
 
-Apply the function `𝒻` to every node in the tree with root `node`.  `node` must satisfy the AbstractTrees interface.
-Instead of returning the result of `𝒻(n)` directly the result will be a tree of [`MapNode`](@ref) objects isomorphic
-to the original tree but with values equal to the corresponding `𝒻(n)`.
+Apply the function `f` to every node in the tree with root `node`.  `node` must satisfy the AbstractTrees interface.
+Instead of returning the result of `f(n)` directly the result will be a tree of [`MapNode`](@ref) objects isomorphic
+to the original tree but with values equal to the corresponding `f(n)`.
 
 Note that in most common cases tree nodes are of a type which depends on their connectedness and the function
-`𝒻` should take this into account.  For example the tree `[1, [2, 3]]` contains integer leaves but two
-`Vector` nodes.  Therefore, the `𝒻` in `treemap(𝒻, [1, [2,3]])` must be a function that is valid for either
+`f` should take this into account.  For example the tree `[1, [2, 3]]` contains integer leaves but two
+`Vector` nodes.  Therefore, the `f` in `treemap(f, [1, [2,3]])` must be a function that is valid for either
 `Int` or `Vector`.  Alternatively, to only operate on leaves do `map(𝒻, Leaves(itr))`.
 
 ## Example
 ```julia
 julia> t = [1, [2, 3]];
 
-julia> 𝒻(x) = x isa AbstractArray ? nothing : x + 1;
+julia> f(x) = x isa AbstractArray ? nothing : x + 1;
 
-julia> treemap(𝒻, t)
+julia> treemap(f, t)
 MapNode{Nothing, MapNode}(nothing)
 ├─ MapNode{Int64, MapNode{Union{}}}(2)
 └─ MapNode{Nothing, MapNode{Int64, MapNode{Union{}}}}(nothing)
    ├─ MapNode{Int64, MapNode{Union{}}}(3)
    └─ MapNode{Int64, MapNode{Union{}}}(4)
 ```
 """
-treemap(𝒻, node) = MapNode(𝒻, node)
+treemap(f, node) = MapNode(f, node)