Update docs

Author: YingboMa

docs/src/IR.md

@@ -3,17 +3,19 @@
 ModelingToolkit IR mirrors the Julia AST but allows for easy mathematical
 manipulation by itself following mathematical semantics. The base of the IR is
 the `Sym` type, which defines a symbolic variable. Registered (mathematical)
-functions on `Sym`s (or `Term`s) return `Term`s.  For example, `op1 = x+y` is
-one `Term` and `op2 = 2z` is another, and so `op1*op2` is another `Term`. Then,
-at the top, an `Equation`, normally written as `op1 ~ op2`, defines the
-symbolic equality between two operations.
+functions on `Sym`s (or `istree` objects) return an expression that `istree`.
+For example, `op1 = x+y` is one symbolic object and `op2 = 2z` is another, and
+so `op1*op2` is another tree object. Then, at the top, an `Equation`, normally
+written as `op1 ~ op2`, defines the symbolic equality between two operations.
 
 ### Types
 `Sym`, `Term`, and `FnType` are from [SymbolicUtils.jl](https://juliasymbolics.github.io/SymbolicUtils.jl/api/). Note that in
 ModelingToolkit, we always use `Sym{Real}`, `Term{Real}`, and
-`FnType{Tuple{Any}, Real}`. To get the arguments of a `Term` use
-`arguments(t::Term)`, and to get the operation of a `Term` use
-`operation(t::Term)`.
+`FnType{Tuple{Any}, Real}`. To get the arguments of a `istree` object use
+`arguments(t::Term)`, and to get the operation, use `operation(t::Term)`.
+However, note that one should never dispatch on `Term` or test `isa Term`.
+Instead, one needs to use `SymbolicUtils.istree` to check if `arguments` and
+`operation` is defined.
 
 ```@docs
 Equation

docs/src/tutorials/symbolic_functions.md

@@ -7,17 +7,15 @@ The way to define symbolic variables is via the `@variables` macro:
 @variables x y
 ```
 
-After defining variables as symbolic, symbolic expressions, which we
-call a `Term`, can be generated by utilizing Julia expressions.
-For example:
+After defining variables as symbolic, symbolic expressions, which we call a
+`istree` object, can be generated by utilizing Julia expressions. For example:
 
 ```julia
 z = x^2 + y
 ```
 
-Here, `z` is the `Term` for "square `x` and add `y`". To
-make an array of symbolic expressions, simply make an array of
-symbolic expressions:
+Here, `z` is an expression tree for "square `x` and add `y`". To make an array
+of symbolic expressions, simply make an array of symbolic expressions:
 
 ```julia
 A = [x^2+y 0 2x
@@ -30,7 +28,10 @@ A = [x^2+y 0 2x
   y ^ 2 + x  0  0
 ```
 
-Note that by default, `@variables` returns `Sym` or `Term` objects wrapped in `Num` in order to make them behave like subtypes of `Real`. Any operation on these `Num` objects will return a new `Num` object, wrapping the result of computing symbolically on the underlying values.
+Note that by default, `@variables` returns `Sym` or `istree` objects wrapped in
+`Num` in order to make them behave like subtypes of `Real`. Any operation on
+these `Num` objects will return a new `Num` object, wrapping the result of
+computing symbolically on the underlying values.
 
 To better view the results, we can use [Latexify.jl](https://github.com/korsbo/Latexify.jl).
 ModelingToolkit.jl comes with Latexify recipes so it works automatically: