docs: describe generic getters and setters

Author: MilesCranmer

docs/src/api.md

@@ -75,6 +75,42 @@ You can create a copy of a node with `copy_node`:
 copy_node
 ```
 
+## Generic Node Accessors
+
+For working with nodes of arbitrary arity:
+
+```@docs
+get_child
+set_child!
+get_children
+set_children!
+```
+
+Examples:
+
+```julia
+# Define operators including ternary
+my_ternary(x, y, z) = x + y * z
+operators = OperatorEnum(((sin,), (+, *), (my_ternary,)))  # (unary, binary, ternary)
+
+tree = Node{Float64,3}(; op=1, children=(Node{Float64,3}(; val=1.0), Node{Float64,3}(; val=2.0)))
+new_child = Node{Float64,3}(; val=3.0)
+
+left_child = get_child(tree, 1)
+right_child = get_child(tree, 2)
+
+set_child!(tree, new_child, 1)
+
+children = get_children(tree)
+left, right = get_children(tree, Val(2))  # type stable
+
+# Transform to ternary operation
+child1, child2, child3 = Node{Float64,3}(; val=4.0), Node{Float64,3}(; val=5.0), Node{Float64,3}(; val=6.0)
+set_children!(tree, (child1, child2, child3))
+tree.op = 1  # my_ternary
+tree.degree = 3
+```
+
 ## Graph Nodes
 
 You can describe an equation as a *graph* rather than a tree
@@ -109,7 +145,7 @@ This means that we only need to change it once
 to have changes propagate across the expression:
 
 ```julia
-julia> y.r.val *= 0.9
+julia> get_child(y, 2).val *= 0.9
 1.35
 
 julia> z

src/Node.jl

@@ -117,6 +117,9 @@ nodes, you can evaluate or print a given expression.
     object. Only defined if `degree >= 1`
 - `children::NTuple{D,Node{T,D}}`: Children of the node. Only defined up to `degree`
 
+For accessing and modifying children, use [`get_child`](@ref), [`set_child!`](@ref),
+[`get_children`](@ref), and [`set_children!`](@ref).
+
 # Constructors
 
 
@@ -188,17 +191,46 @@ end
 @inline function get_children(node::AbstractNode)
     return getfield(node, :children)
 end
+
+"""
+    get_children(node::AbstractNode)
+    get_children(node::AbstractNode, ::Val{n})
+
+Return the children tuple of a node. The first form returns the complete children tuple as stored.
+The second form returns a tuple of exactly `n` children, useful for type stability when the
+number of children needed is known at compile time.
+"""
 @inline function get_children(node::AbstractNode, ::Val{n}) where {n}
     cs = get_children(node)
     return ntuple(i -> cs[i], Val(Int(n)))
 end
+
+"""
+    get_child(node::AbstractNode, i::Integer)
+
+Return the `i`-th child of a node (1-indexed).
+"""
 @inline function get_child(n::AbstractNode{D}, i::Int) where {D}
     return get_children(n)[i]
 end
+
+"""
+    set_child!(node::AbstractNode, child::AbstractNode, i::Integer)
+
+Replace the `i`-th child of a node (1-indexed) with the given child node.
+Returns the new child. Updates the children tuple in-place.
+"""
 @inline function set_child!(n::AbstractNode{D}, child::AbstractNode{D}, i::Int) where {D}
     set_children!(n, Base.setindex(get_children(n), child, i))
     return child
 end
+
+"""
+    set_children!(node::AbstractNode, children::Tuple)
+
+Replace all children of a node with the given tuple. If fewer children are
+provided than the node's maximum degree, remaining slots are filled with poison nodes.
+"""
 @inline function set_children!(n::AbstractNode{D}, children::Union{Tuple,AbstractVector{<:AbstractNode{D}}}) where {D}
     D2 = length(children)
     if D === D2

src/Simplify.jl

@@ -74,15 +74,15 @@ function combine_operators(tree::Node{T,2}, operators::AbstractOperatorEnum) whe
                     #(const - (const - var)) => (var - const)
                     l = get_child(tree, 1)
                     r = get_child(tree, 2)
-                    simplified_const = (get_child(r, 1).val - l.val) #neg(sub(l.val, r.l.val))
+                    simplified_const = (get_child(r, 1).val - l.val) #neg(sub(l.val, get_child(r, 1).val))
                     set_child!(tree, get_child(get_child(tree, 2), 2), 1)
                     set_child!(tree, l, 2)
                     get_child(tree, 2).val = simplified_const
                 elseif is_node_constant(get_child(get_child(tree, 2), 2))
                     #(const - (var - const)) => (const - var)
                     l = get_child(tree, 1)
                     r = get_child(tree, 2)
-                    simplified_const = l.val + get_child(r, 2).val #plus(l.val, r.r.val)
+                    simplified_const = l.val + get_child(r, 2).val #plus(l.val, get_child(r, 2).val)
                     set_child!(tree, get_child(get_child(tree, 2), 1), 2)
                     get_child(tree, 1).val = simplified_const
                 end
@@ -93,15 +93,15 @@ function combine_operators(tree::Node{T,2}, operators::AbstractOperatorEnum) whe
                     #((const - var) - const) => (const - var)
                     l = get_child(tree, 1)
                     r = get_child(tree, 2)
-                    simplified_const = get_child(l, 1).val - r.val#sub(l.l.val, r.val)
+                    simplified_const = get_child(l, 1).val - r.val#sub(get_child(l, 1).val, r.val)
                     set_child!(tree, get_child(get_child(tree, 1), 2), 2)
                     set_child!(tree, r, 1)
                     get_child(tree, 1).val = simplified_const
                 elseif is_node_constant(get_child(get_child(tree, 1), 2))
                     #((var - const) - const) => (var - const)
                     l = get_child(tree, 1)
                     r = get_child(tree, 2)
-                    simplified_const = r.val + get_child(l, 2).val #plus(r.val, l.r.val)
+                    simplified_const = r.val + get_child(l, 2).val #plus(r.val, get_child(l, 2).val)
                     set_child!(tree, get_child(get_child(tree, 1), 1), 1)
                     get_child(tree, 2).val = simplified_const
                 end