Update API on README

Author: MilesCranmer

README.md

@@ -159,19 +159,28 @@ x1 = Node(String; feature=1)
 This node, will be used to index input data (whatever it may be) with either `data[feature]` (1D abstract arrays) or `selectdim(data, 1, feature)` (ND abstract arrays). Let's now define some operators to use:
 
 ```julia
-my_string_func(x::String) = "Hello $x"
+my_string_func(x::String) = "ello $x"
 
 operators = GenericOperatorEnum(;
     binary_operators=[*],
-    unary_operators=[my_string_func],
-    extend_user_operators=true)
+    unary_operators=[my_string_func]
+)
+```
+
+Now, let's extend our operators to work with the
+expression types used by `DynamicExpressions.jl`:
+
+```julia
+@extend_operators operators
 ```
 
 Now, let's create an expression:
 
 ```julia
-tree = x1 * " World!"
-tree(["Hello", "Me?"])
+tree = "H" * my_string_func(x1)
+# ^ `(H * my_string_func(x1))`
+
+tree(["World!", "Me?"])
 # Hello World!
 ```
 
@@ -202,7 +211,8 @@ vec_add(x, y) = x .+ y
 vec_square(x) = x .* x
 
 # Set up an operator enum:
-operators = GenericOperatorEnum(;binary_operators=[vec_add], unary_operators=[vec_square], extend_user_operators=true)
+operators = GenericOperatorEnum(;binary_operators=[vec_add], unary_operators=[vec_square])
+@extend_operators operators
 
 # Construct the expression:
 tree = vec_add(vec_add(vec_square(x1), c2), c1)

docs/src/types.md

@@ -13,16 +13,35 @@ OperatorEnum
 Construct this operator specification as follows:
 
 ```@docs
-OperatorEnum(; binary_operators, unary_operators, enable_autodiff)
+OperatorEnum(; binary_operators=[], unary_operators=[], enable_autodiff::Bool=false, define_helper_functions::Bool=true)
 ```
 
 This is just for scalar real operators. However, you can use
 the following for more general operators:
 
 ```@docs
-GenericOperatorEnum(; binary_operators=[], unary_operators=[], extend_user_operators::Bool=false)
+GenericOperatorEnum(; binary_operators=[], unary_operators=[], define_helper_functions::Bool=true)
 ```
 
+By default, these operators will define helper functions for constructing trees,
+so that you can write `Node(;feature=1) + Node(;feature=2)` instead of
+`Node(1, Node(;feature=1), Node(;feature=2))` (assuming `+` is the first operator).
+You can turn this off with `define_helper_functions=false`.
+
+For other operators *not* found in `Base`, including user-defined functions, you may
+use the `@extend_operators` macro:
+
+```@docs
+@extend_operators operators
+```
+
+This will extend the operators you have passed to work with `Node` types, so that
+it is easier to construct expression trees.
+
+Note that you are free to use the `Node` constructors directly.
+This is a more robust approach, and should be used when creating libraries
+which use `DynamicExpressions.jl`.
+
 ## Equations
 
 Equations are specified as binary trees with the `Node` type, defined

src/OperatorEnumConstruction.jl

@@ -166,7 +166,7 @@ function _extend_operators(operators, skip_user_operators, __module__::Module)
 end
 
 """
-    @extend_operators(operators)
+    @extend_operators operators
 
 Extends all operators defined in this operator enum to work on the
 `Node` type. While by default this is already done for operators defined
@@ -187,7 +187,7 @@ macro extend_operators(operators)
 end
 
 """
-    @extend_operators_base(operators)
+    @extend_operators_base operators
 
 Similar to `@extend_operators`, but only extends operators already
 defined in `Base`.

test/test_tree_construction.jl

@@ -112,14 +112,16 @@ function op1(x, y)
     return x + y
 end
 function op2(x, y)
-    return x ^ 2 + 1/((y)^2 + 0.1)
+    return x^2 + 1 / ((y)^2 + 0.1)
 end
 function op3(x)
     return sin(x) + cos(x)
 end
-operators = OperatorEnum(; default_params..., binary_operators=(op1, op2), unary_operators=(op3,))
+operators = OperatorEnum(;
+    default_params..., binary_operators=(op1, op2), unary_operators=(op3,)
+)
 @extend_operators operators
 x1 = Node(; feature=1)
 x2 = Node(; feature=2)
 tree = op1(op2(x1, x2), op3(x1))
-@test repr(tree) == "op1(op2(x1, x2), op3(x1))"
+@test repr(tree) == "op1(op2(x1, x2), op3(x1))"