a bit more docs

Author: ChrisRackauckas

docs/src/IR.md

@@ -50,7 +50,15 @@ of the differentials down to basic one-variable expressions.
 Differential
 expand_derivatives
 ModelingToolkit.derivative
+ModelingToolkit.gradient
+ModelingToolkit.jacobian
+ModelingToolkit.hessian
 ```
+
+Note that generation of sparse matrices simply follows from the Julian semantics
+imbued on the IR, so `sparse(jac)` changes a dense Jacobian to a sparse Jacobian
+matrix.
+
 ### Adding Derivatives
 
 There is a large amount of derivatives pre-defined by

src/direct.jl

@@ -1,13 +1,37 @@
+"""
+```julia
+gradient(O::Expression, vars::AbstractVector{<:Expression}; simplify = true)
+```
+
+A helper function for computing the gradient of an expression with respect to
+an array of variable expressions.
+"""
 function gradient(O::Expression, vars::AbstractVector{<:Expression}; simplify = true)
     out = [expand_derivatives(Differential(v)(O)) for v in vars]
     simplify ? simplify_constants.(out) : out
 end
 
+"""
+```julia
+jacobian(O::Expression, vars::AbstractVector{<:Expression}; simplify = true)
+```
+
+A helper function for computing the Jacobian of an array of expressions with respect to
+an array of variable expressions.
+"""
 function jacobian(ops::AbstractVector{<:Expression}, vars::AbstractVector{<:Expression}; simplify = true)
     out = [expand_derivatives(Differential(v)(O)) for O in ops, v in vars]
     simplify ? simplify_constants.(out) : out
 end
 
+"""
+```julia
+hessian(O::Expression, vars::AbstractVector{<:Expression}; simplify = true)
+```
+
+A helper function for computing the Hessian of an expression with respect to
+an array of variable expressions.
+"""
 function hessian(O::Expression, vars::AbstractVector{<:Expression}; simplify = true)
     out = [expand_derivatives(Differential(v2)(Differential(v1)(O))) for v1 in vars, v2 in vars]
     simplify ? simplify_constants.(out) : out