add some docs

Author: shashi

docs/api.md

@@ -20,6 +20,12 @@ using SymbolicUtils # hide
 
 {{doc Term Term type}}
 
+{{doc Add Add type}}
+
+{{doc Mul Mul type}}
+
+{{doc Pow Pow type}}
+
 {{doc promote_symtype promote_symtype fn}}
 
 ## Interfacing

docs/index.md

@@ -12,18 +12,20 @@ where appropriate -->
 
 The main features are:
 
-- Symbols (`Sym`s) carry type information. ([read more](#symbolic_expressions))
-- Compound expressions composed of `Sym`s propagate type information. ([read more](#symbolic_expressions))
-- A flexible [rule-based rewriting language](#rule-based_rewriting) allowing liberal use of user defined matchers and rewriters.
+- Fast expressions
 - A [combinator library](#composing-rewriters) for making rewriters.
+- A [rule-based rewriting language](#rule-based_rewriting).
+- Type promotion:
+  - Symbols (`Sym`s) carry type information. ([read more](#symbolic_expressions))
+  - Compound expressions composed of `Sym`s propagate type information. ([read more](#symbolic_expressions))
 - Set of [simplification rules](#simplification). These can be remixed and extended for special purposes.
 
 
 ## Table of contents
 
 \tableofcontents <!-- you can use \toc as well -->
 
-## Symbolic expressions
+## `Sym`s
 
 First, let's use the `@syms` macro to create a few symbols.
 
@@ -66,17 +68,6 @@ expr1 + expr2
 ```
 \out{expr}
 
-### Simplified printing
-
-Tip: you can set `SymbolicUtils.show_simplified[] = true` to enable simplification on printing, or call `SymbolicUtils.showraw(expr)` to display an expression without simplification.
- In the REPL, if an expression was successfully simplified before printing, it will appear in yellow rather than white, as a visual cue that what you are looking at is not the exact datastructure. 
-
-```julia:showraw
-using SymbolicUtils: showraw
-
-showraw(expr1 + expr2)
-```
-\out{showraw}
 
 **Function-like symbols**
 
@@ -106,6 +97,20 @@ g(2//5, g(1, β))
 
 This works because `g` "returns" a `Real`.
 
+
+## Expression interface
+
+Symbolic expressions are of type `Term{T}`, `Add{T}`, `Mul{T}` or `Pow{T}` and denote some function call where one or more arguments are themselves such expressions or `Sym`s.
+
+All the expression types support the following:
+
+- `istree(x)` -- always returns `true` denoting, `x` is not a leaf node like Sym or a literal.
+- `operation(x)` -- the function being called
+- `arguments(x)` -- a vector of arguments
+- `symtype(x)` -- the "inferred" type (`T`)
+
+See more on the interface [here](/interface)
+
 ## Rule-based rewriting
 
 Rewrite rules match and transform an expression. A rule is written using either the `@rule` macro or the `@acrule` macro.
@@ -151,7 +156,7 @@ Notice that there is a subexpression `(2 * w) + (2 * w)` that could be simplifie
 
 ### Predicates for matching
 
-Matcher pattern may contain slot variables with attached predicates, written as `~x::f` where `f` is a function that takes a matched expression (a `Term` object a `Sym` or any Julia value that is in the expression tree) and returns a boolean value. Such a slot will be considered a match only if `f` returns true.
+Matcher pattern may contain slot variables with attached predicates, written as `~x::f` where `f` is a function that takes a matched expression and returns a boolean value. Such a slot will be considered a match only if `f` returns true.
 
 Similarly `~~x::g` is a way of attaching a predicate `g` to a segment variable. In the case of segment variables `g` gets a vector of 0 or more expressions and must return a boolean value. If the same slot or segment variable appears twice in the matcher pattern, then at most one of the occurance should have a predicate.
 

src/types.jl

@@ -391,12 +391,17 @@ sdict(kv...) = Dict{Any, Number}(kv...)
 # this cannot be Symbolic{<:Number} to make MTK Parameters work. See #155
 const SN = Symbolic
 """
-    Add(coeff, dict)
+    Add(T, coeff, dict::Dict)
 
-Represents coeff + (key1 * val1) + (key2 * val2) + ...
+Represents `coeff + (key1 * val1) + (key2 * val2) + ...`
 
-where coeff and the vals are non-symbolic numbers.
+where keys and values come from the dictionary (`dict`).
+where `coeff` and the vals are `<:Number` and keys are symbolic.
 
+- `operation(::Add)` -- returns `+`.
+- `symtype(::Add)` -- returns `T`.
+- `arguments(::Add)` -- returns a totally ordered vector of arguments. i.e.
+  `[coeff, keyM*valM, keyN*valN...]`
 """
 struct Add{X, T<:Number, D} <: Symbolic{X}
     coeff::T
@@ -507,11 +512,17 @@ end
 -(a::SN, b::Number) = a + (-b)
 
 """
-    Mul(coeff, dict)
+    Mul(T, coeff, dict)
 
 Represents coeff * (key1 ^ val1) * (key2 ^ val2) * ....
 
-where coeff is a non-symbolic number.
+where coeff is a <:Number and keys and values come from the dictionary (`dict`).
+where `coeff` and the vals are `<:Number` and keys are symbolic.
+
+- `symtype(::Add)` -- returns `T`.
+- `operation(::Add)` -- returns `*`.
+- `arguments(::Add)` -- returns a totally ordered vector of arguments. i.e.
+  `[coeff, keyM^valM, keyN^valN...]`
 """
 struct Mul{X, T<:Number, D} <: Symbolic{X}
     coeff::T
@@ -552,9 +563,6 @@ Base.isequal(a::Mul, b::Mul) = isequal(a.coeff, b.coeff) && isequal(a.dict, b.di
 
 Base.show(io::IO, a::Mul) = show_term(io, a)
 
-"""
-makemul(xs...)
-"""
 function makemul(sign, coeff, xs...; d=sdict())
     for x in xs
         if x isa Pow && x.exp isa Number
@@ -606,7 +614,7 @@ end
 """
     Pow(base, exp)
 
-Represents base^exp, a lighter version of Mul(1, Dict(base=>exp))
+Represents `base^exp`, a lighter version of `Mul(1, Dict(base=>exp))`
 """
 struct Pow{X, B, E} <: Symbolic{X}
     base::B