Update documentation for JuliaFunc and StdStr

Author: asterycs

docs/src/usage.md

@@ -110,13 +110,13 @@ x₃x³A¹₆ + 2A¹₅x⁵x₆
 
 See [Derivatives in Standard Notation](@ref) for more examples.
 
-## Converting Tensor Expression to Standard Notation
+## Converting Tensor Expressions to Standard Notation
 
 An expression in Ricci-notation can be converted back to standard notation using [`to_std`](@ref). `DiffMatic` can output a standard expression in string format or as a Julia function.
 
 ### String Output
 
-An expression can be converted to standard matrix notation and retrieved as a string by passing [`StdStr`](@ref) as a keyword argument to [`to_std`](@ref):
+An expression can be converted to standard matrix notation and retrieved as a string by passing a [`StdStr`](@ref) instance as a keyword argument `format` to [`to_std`](@ref):
 
 ```jldoctest usage
 to_std(J; format = StdStr())
@@ -128,6 +128,7 @@ to_std(J; format = StdStr())
 
 Special notation used in the output:
   - "⊙": Element-wise multiplication.
+  - "⊘": Element-wise division.
   - "diag(x)": Diagonal matrix with "x" on the diagonal.
   - "vec(1)": Vector consisting of 1:s.
   - "sgn(x)": The signum function applied element-wise.
@@ -136,7 +137,7 @@ Special notation used in the output:
 
 ### Julia Function
 
-A Julia function is generated by passing [`JuliaFunc`](@ref) as a keyword argument to [`to_std`](@ref). The function is returned in the form of an [expression](https://docs.julialang.org/en/v1/manual/metaprogramming/#Expressions-and-evaluation):
+A Julia function is generated by passing a [`JuliaFunc`](@ref) instance as a keyword argument `format` to [`to_std`](@ref). The function is returned in the form of an [expression](https://docs.julialang.org/en/v1/manual/metaprogramming/#Expressions-and-evaluation):
 
 ```julia
 to_std(g; format = JuliaFunc())
@@ -145,10 +146,10 @@ to_std(g; format = JuliaFunc())
 
 quote
     #= ... =#
-    function (B, A, x)
+    function (A, B, x)
         #= ... =#
         #= ... =#
-        return 2 * (transpose(B) * (transpose(A) * x)) + 2 * ((A * B) * x)
+        return 2 * ((transpose(B) * transpose(A)) * x) + 2 * (A * (B * x))
     end
 end
 ```
@@ -172,5 +173,51 @@ g_fun(An, Bn, xn)
  450.0
 ```
 
+The `JuliaFunc` generator may use functions and primitives defined in `LinearAlgebra`, such as e.g. `diagm` and `I`. These functions need to be explicitly imported by the user prior to usage:
+
+```jldoctest usage
+g = gradient(log.(A * x)' * x, x)
+g_fun = eval(to_std(g; format = JuliaFunc()))
+
+An = exp(3) * ones(3,3)
+xn = Float64[1; 0; 0]
+
+g_fun(An, xn)
+
+# output
+
+ERROR: UndefVarError: `diagm` not defined
+```
+
+```jldoctest usage
+using LinearAlgebra: diagm
+
+g_fun(An, xn)
+
+# output
+
+3-element Vector{Float64}:
+ 4.0
+ 4.0
+ 4.0
+```
+
+The order of the arguments of the generated function can be specified through `JuliaFunc`:
+```julia
+to_std(g; format = JuliaFunc([x, B, A]))
+
+# output
+
+quote
+    #= ... =#
+    function (x, B, A)
+        #= ... =#
+        #= ... =#
+        return 2 * ((transpose(B) * transpose(A)) * x) + 2 * (A * (B * x))
+    end
+end
+
+```
+
 ```@bibliography
 ```