some docs

Author: shashi

src/polyform.jl

@@ -9,6 +9,22 @@ Abstracts a [MultivariatePolynomials.jl](https://juliaalgebra.github.io/Multivar
 
 The SymbolicUtils term interface (`istree`, `operation, and `arguments`) works on PolyForm lazily: the `operation` and `arguments` are created by converting one level of arguments into SymbolicUtils expressions. They may further contain PolyForm within them.
 We use this to hold polynomials in memory while doing `simplify_fractions`.
+
+    PolyForm{T}(x; Fs=Union{typeof(*),typeof(+),typeof(^)}, recurse=false)
+
+Turn a Symbolic expression `x` into a polynomial and return a PolyForm that abstracts it.
+
+`Fs` are the types of functions which should be applied if arguments are themselves
+polynomialized. For example, if you only want to polynomialize the base of power
+expressions, you would  leave out `typeof(^)` from the union. In this case `^`
+is not called, but maintained as a `Pow` term.
+
+`recurse` is a flag which calls `PolyForm` recursively on subexpressions. For example:
+
+```julia
+PolyForm(sin((x+y)^2))               #=> sin((x+y)^2)
+PolyForm(sin((x+y)^2), recurse=true) #=> sin((x^2 + (2x)y + y^2))
+```
 """
 struct PolyForm{T, M} <: Symbolic{T}
     p::MP.AbstractPolynomialLike
@@ -213,6 +229,8 @@ expand(expr) = PolyForm(expr)
 function polyform_factors(d::Div, pvar2sym, sym2term)
     make(xs) = map(xs) do x
         if x isa Pow && arguments(x)[2] isa Integer && arguments(x)[2] > 0
+            # here we do want to recurse one level, that's why it's wrong to just
+            # use Fs = Union{typeof(+), typeof(*)} here.
             Pow(PolyForm(arguments(x)[1], pvar2sym, sym2term), arguments(x)[2])
         else
             PolyForm(x, pvar2sym, sym2term)
@@ -242,6 +260,12 @@ function add_divs(x::Div, y::Div)
     Div(_mul(x_num, y_den) + _mul(x_den, y_num), _mul(x_den, y_den))
 end
 
+"""
+    simplify_fractions(x)
+
+Find `Div` nodes and simplify them by cancelling a set of factors of numerators
+and denominators. It may leave some expressions in `PolyForm` format.
+"""
 function simplify_fractions(x)
     isdiv(x) = x isa Div