Add docstrings for convenience calls

Author: MilesCranmer

docs/src/eval.md

@@ -8,13 +8,34 @@ eval_tree_array(tree::Node{T}, cX::AbstractMatrix{T}, operators::OperatorEnum) w
 ```
 
 Assuming you are only using a single `OperatorEnum`, you can also use
-the following short-hand by using the expression as a function:
+the following shorthand by using the expression as a function:
+
+```
+    (tree::Node)(X::AbstractMatrix{T}, operators::OperatorEnum; turbo::Bool=false)
+
+Evaluate a binary tree (equation) over a given data matrix. The
+operators contain all of the operators used in the tree.
+
+# Arguments
+- `X::AbstractMatrix{T}`: The input data to evaluate the tree on.
+- `operators::OperatorEnum`: The operators used in the tree.
+- `turbo::Bool`: Use `LoopVectorization.@turbo` for faster evaluation.
+
+# Returns
+- `output::AbstractVector{T}`: the result, which is a 1D array.
+    Any NaN, Inf, or other failure during the evaluation will result in the entire
+    output array being set to NaN.
+```
+
+For example,
 
 ```@example
+using DynamicExpressions
+
 operators = OperatorEnum(; binary_operators=[+, -, *], unary_operators=[cos])
 tree = Node(; feature=1) * cos(Node(; feature=2) - 3.2)
 
-tree(X)
+tree([1 2 3; 4 5 6.], operators)
 ```
 
 This is possible because when you call `OperatorEnum`, it automatically re-defines
@@ -32,7 +53,31 @@ The notation is the same for `eval_tree_array`, though it will return `nothing`
 when it can't find a method, and not do any NaN checks:
 
 ```@docs
-    eval_tree_array(tree, cX::AbstractArray, operators::GenericOperatorEnum; throw_errors::Bool=true)
+eval_tree_array(tree::Node, cX::AbstractMatrix, operators::GenericOperatorEnum; throw_errors::Bool=true)
+```
+
+Likewise for the shorthand notation:
+
+```
+    (tree::Node)(X::AbstractMatrix, operators::GenericOperatorEnum; throw_errors::Bool=true)
+
+# Arguments
+- `X::AbstractArray`: The input data to evaluate the tree on.
+- `operators::GenericOperatorEnum`: The operators used in the tree.
+- `throw_errors::Bool=true`: Whether to throw errors
+    if they occur during evaluation. Otherwise,
+    MethodErrors will be caught before they happen and 
+    evaluation will return `nothing`,
+    rather than throwing an error. This is useful in cases
+    where you are unsure if a particular tree is valid or not,
+    and would prefer to work with `nothing` as an output.
+
+# Returns
+- `output`: the result of the evaluation.
+    If evaluation failed, `nothing` will be returned for the first argument.
+    A `false` complete means an operator was called on input types
+    that it was not defined for. You can change this behavior by
+    setting `throw_errors=false`.
 ```
 
 ## Derivatives
@@ -46,7 +91,32 @@ all variables (or, all constants). Both use forward-mode automatic, but use
 
 ```@docs
 eval_diff_tree_array(tree::Node{T}, cX::AbstractMatrix{T}, operators::OperatorEnum, direction::Int) where {T<:Number}
-eval_grad_tree_array(tree::Node{T}, cX::AbstractMatrix{T}, operators::OperatorEnum; variable::Bool=false) where {T<:Number}
+eval_grad_tree_array(tree::Node{T}, cX::AbstractMatrix{T}, operators::OperatorEnum; turbo::Bool=false, variable::Bool=false) where {T<:Number}
+```
+
+You can compute gradients this with shorthand notation as well (which by default computes
+gradients with respect to input matrix, rather than constants).
+
+```
+    (tree::Node{T})'(X::AbstractMatrix{T}, operators::OperatorEnum; turbo::Bool=false, variable::Bool=true)
+
+Compute the forward-mode derivative of an expression, using a similar
+structure and optimization to eval_tree_array. `variable` specifies whether
+we should take derivatives with respect to features (i.e., X), or with respect
+to every constant in the expression.
+
+# Arguments
+- `X::AbstractMatrix{T}`: The data matrix, with each column being a data point.
+- `operators::OperatorEnum`: The operators used to create the `tree`. Note that `operators.enable_autodiff`
+    must be `true`. This is needed to create the derivative operations.
+- `variable::Bool`: Whether to take derivatives with respect to features (i.e., `X` - with `variable=true`),
+    or with respect to every constant in the expression (`variable=false`).
+- `turbo::Bool`: Use `LoopVectorization.@turbo` for faster evaluation.
+
+# Returns
+
+- `(evaluation, gradient, complete)::Tuple{AbstractVector{T}, AbstractMatrix{T}, Bool}`: the normal evaluation,
+    the gradient, and whether the evaluation completed as normal (or encountered a nan or inf).
 ```
 
 Alternatively, you can compute higher-order derivatives by using `ForwardDiff` on

src/EvaluationHelpers.jl

@@ -7,11 +7,48 @@ import ..EvaluateEquationModule: eval_tree_array
 import ..EvaluateEquationDerivativeModule: eval_grad_tree_array
 
 # Evaluation:
+"""
+    (tree::Node)(X::AbstractMatrix{T}, operators::OperatorEnum; turbo::Bool=false)
+
+Evaluate a binary tree (equation) over a given data matrix. The
+operators contain all of the operators used in the tree.
+
+# Arguments
+- `X::AbstractMatrix{T}`: The input data to evaluate the tree on.
+- `operators::OperatorEnum`: The operators used in the tree.
+- `turbo::Bool`: Use `LoopVectorization.@turbo` for faster evaluation.
+
+# Returns
+- `output::AbstractVector{T}`: the result, which is a 1D array.
+    Any NaN, Inf, or other failure during the evaluation will result in the entire
+    output array being set to NaN.
+"""
 function (tree::Node)(X, operators::OperatorEnum; kws...)
     out, did_finish = eval_tree_array(tree, X, operators; kws...)
     !did_finish && (out .= convert(eltype(out), NaN))
     return out
 end
+"""
+    (tree::Node)(X::AbstractMatrix, operators::GenericOperatorEnum; throw_errors::Bool=true)
+
+# Arguments
+- `X::AbstractArray`: The input data to evaluate the tree on.
+- `operators::GenericOperatorEnum`: The operators used in the tree.
+- `throw_errors::Bool=true`: Whether to throw errors
+    if they occur during evaluation. Otherwise,
+    MethodErrors will be caught before they happen and 
+    evaluation will return `nothing`,
+    rather than throwing an error. This is useful in cases
+    where you are unsure if a particular tree is valid or not,
+    and would prefer to work with `nothing` as an output.
+
+# Returns
+- `output`: the result of the evaluation.
+    If evaluation failed, `nothing` will be returned for the first argument.
+    A `false` complete means an operator was called on input types
+    that it was not defined for. You can change this behavior by
+    setting `throw_errors=false`.
+"""
 function (tree::Node)(X, operators::GenericOperatorEnum; kws...)
     out, did_finish = eval_tree_array(tree, X, operators; kws...)
     !did_finish && return nothing
@@ -37,6 +74,28 @@ function _grad_evaluator(tree::Node, X; kws...)
     ## into a depwarn
     @error "The `tree'(X; kws...)` syntax is deprecated. Use `tree'(X, operators; kws...)` instead."
 end
+
+"""
+    (tree::Node{T})'(X::AbstractMatrix{T}, operators::OperatorEnum; turbo::Bool=false, variable::Bool=true)
+
+Compute the forward-mode derivative of an expression, using a similar
+structure and optimization to eval_tree_array. `variable` specifies whether
+we should take derivatives with respect to features (i.e., X), or with respect
+to every constant in the expression.
+
+# Arguments
+- `X::AbstractMatrix{T}`: The data matrix, with each column being a data point.
+- `operators::OperatorEnum`: The operators used to create the `tree`. Note that `operators.enable_autodiff`
+    must be `true`. This is needed to create the derivative operations.
+- `variable::Bool`: Whether to take derivatives with respect to features (i.e., `X` - with `variable=true`),
+    or with respect to every constant in the expression (`variable=false`).
+- `turbo::Bool`: Use `LoopVectorization.@turbo` for faster evaluation.
+
+# Returns
+
+- `(evaluation, gradient, complete)::Tuple{AbstractVector{T}, AbstractMatrix{T}, Bool}`: the normal evaluation,
+    the gradient, and whether the evaluation completed as normal (or encountered a nan or inf).
+"""
 Base.adjoint(tree::Node) = ((args...; kws...) -> _grad_evaluator(tree, args...; kws...))
 
 end