Merge pull request #775 from ChrisRackauckas-Claude/add-missing-docstrings

Add comprehensive docstrings for all public API functions

Author: ChrisRackauckas

docs/src/api.md

@@ -1,33 +1,117 @@
 # API Reference
 
 ## Symbols and Terms
+
+### Creating Symbols and Terms
 ```@docs
 SymbolicUtils.@syms
+SymbolicUtils.term
 SymbolicUtils.Sym
+```
+
+### Inspecting Terms
+```@docs
 SymbolicUtils.issym
 SymbolicUtils.symtype
+SymbolicUtils.iscall
+SymbolicUtils.operation
+SymbolicUtils.arguments
+SymbolicUtils.sorted_arguments
+SymbolicUtils.showraw
+```
+
+### Term Types
+```@docs
 SymbolicUtils.Term
 SymbolicUtils.Add
 SymbolicUtils.Mul
 SymbolicUtils.Pow
+```
+
+### Metadata
+```@docs
+SymbolicUtils.hasmetadata
+SymbolicUtils.getmetadata
+SymbolicUtils.setmetadata
+```
+
+### Type Promotion
+```@docs
 SymbolicUtils.promote_symtype
 ```
 
-## Rewriters
+## Rewriting System
 
+### Rule Creation
 ```@docs
 @rule
+@acrule
+```
+
+### Rewriters
+```@docs
 SymbolicUtils.Rewriters
+SymbolicUtils.Rewriters.Empty
+SymbolicUtils.Rewriters.IfElse
+SymbolicUtils.Rewriters.If
+SymbolicUtils.Rewriters.Chain
+SymbolicUtils.Rewriters.RestartedChain
+SymbolicUtils.Rewriters.Fixpoint
+SymbolicUtils.Rewriters.FixpointNoCycle
+SymbolicUtils.Rewriters.Postwalk
+SymbolicUtils.Rewriters.Prewalk
+SymbolicUtils.Rewriters.PassThrough
 ```
 
-## Simplify
+## Simplification and Transformation
 
 ```@docs
 SymbolicUtils.simplify
 SymbolicUtils.expand
 SymbolicUtils.substitute
 ```
 
+## Polynomial Forms
+
+```@docs
+SymbolicUtils.PolyForm
+SymbolicUtils.simplify_fractions
+SymbolicUtils.quick_cancel
+SymbolicUtils.flatten_fractions
+```
+
+## Code Generation
+
+### Core Functions
+```@docs
+SymbolicUtils.toexpr
+SymbolicUtils.cse
+```
+
+### Code Generation Types
+```@docs
+SymbolicUtils.Assignment
+SymbolicUtils.Let
+SymbolicUtils.Func
+SymbolicUtils.DestructuredArgs
+SymbolicUtils.LiteralExpr
+SymbolicUtils.ForLoop
+```
+
+### Array Operations
+```@docs
+SymbolicUtils.SetArray
+SymbolicUtils.MakeArray
+SymbolicUtils.MakeSparseArray
+SymbolicUtils.MakeTuple
+```
+
+### Parallelism
+```@docs
+SymbolicUtils.SpawnFetch
+SymbolicUtils.Multithreaded
+```
+
 ## Utilities
 
 ```@docs

src/code.jl

@@ -666,6 +666,21 @@ function toexpr(a::MakeTuple, st)
     :(($(toexpr.(a.elems, (st,))...),))
 end
 
+"""
+    Multithreaded
+
+A parallelism type for `SpawnFetch` that uses Julia's threading system.
+
+When used with `SpawnFetch{Multithreaded}`, expressions are executed
+in parallel using `Threads.@spawn`.
+
+# Examples
+```julia
+julia> SpawnFetch{Multithreaded}([func1, func2], combine_func)
+```
+
+See also: [`SpawnFetch`](@ref)
+"""
 struct Multithreaded end
 """
     SpawnFetch{ParallelType}(funcs [, args], reduce)
@@ -834,8 +849,22 @@ end
 """
     $(TYPEDSIGNATURES)
 
-Perform Common Subexpression Elimination on the given expression `expr`. Return an
-equivalent `expr` with optimized computation.
+Perform common subexpression elimination on an expression.
+
+This optimization identifies repeated subexpressions and replaces them with
+variables to avoid redundant computation.
+
+# Arguments
+- `expr`: The expression to optimize
+
+# Returns
+An optimized expression with common subexpressions eliminated
+
+# Examples
+```julia
+julia> expr = :(sin(x) + sin(x) * cos(y))
+julia> cse(expr)  # sin(x) is computed only once
+```
 """
 function cse(expr)
     state = CSEState()

src/rewriters.jl

@@ -40,13 +40,45 @@ export Empty, IfElse, If, Chain, RestartedChain, Fixpoint, Postwalk, Prewalk, Pa
 const repr_cache = IdDict()
 cached_repr(x) = Base.get!(()->repr(x), repr_cache, x)
 
+"""
+    Empty()
+
+A rewriter that always returns `nothing`, indicating no rewrite occurred.
+
+This is useful as a placeholder or for conditional rewriting patterns.
+
+# Examples
+```julia
+julia> Empty()(x)
+nothing
+```
+"""
 struct Empty end
 
 (rw::Empty)(x) = nothing
 
 instrument(x, f) = f(x)
 instrument(x::Empty, f) = x
 
+"""
+    IfElse(cond, yes, no)
+
+A conditional rewriter that applies `yes` if `cond(x)` is true, otherwise applies `no`.
+
+# Arguments
+- `cond`: A function that returns true or false for the input
+- `yes`: The rewriter to apply if the condition is true
+- `no`: The rewriter to apply if the condition is false
+
+# Examples
+```julia
+julia> r = IfElse(x -> x > 0, x -> -x, x -> x)
+julia> r(5)  # Returns -5
+julia> r(-3) # Returns -3
+```
+
+See also: [`If`](@ref)
+"""
 struct IfElse{F, A, B}
     cond::F
     yes::A
@@ -59,8 +91,46 @@ function (rw::IfElse)(x)
     rw.cond(x) ?  rw.yes(x) : rw.no(x)
 end
 
+"""
+    If(cond, yes)
+
+A conditional rewriter that applies `yes` if `cond(x)` is true, otherwise returns the input unchanged.
+
+This is equivalent to `IfElse(cond, yes, Empty())`.
+
+# Arguments
+- `cond`: A function that returns true or false for the input
+- `yes`: The rewriter to apply if the condition is true
+
+# Examples
+```julia
+julia> r = If(x -> x > 0, x -> -x)
+julia> r(5)  # Returns -5
+julia> r(-3) # Returns -3 (unchanged)
+```
+"""
 If(f, x) = IfElse(f, x, Empty())
 
+"""
+    Chain(rws; stop_on_match=false)
+
+Apply a sequence of rewriters to an expression, chaining the results.
+
+Each rewriter in the chain receives the result of the previous rewriter.
+If a rewriter returns `nothing`, the input is passed unchanged to the next rewriter.
+
+# Arguments
+- `rws`: A collection of rewriters to apply in sequence
+- `stop_on_match`: If true, stop at the first rewriter that produces a change
+
+# Examples
+```julia
+julia> r1 = @rule sin(~x)^2 + cos(~x)^2 => 1
+julia> r2 = @rule sin(2*(~x)) => 2*sin(~x)*cos(~x)
+julia> chain = Chain([r1, r2])
+julia> chain(sin(x)^2 + cos(x)^2)  # Returns 1
+```
+"""
 struct Chain
     rws
     stop_on_match::Bool
@@ -83,6 +153,25 @@ function (rw::Chain)(x)
 end
 instrument(c::Chain, f) = Chain(map(x->instrument(x,f), c.rws))
 
+"""
+    RestartedChain(rws)
+
+Apply rewriters in sequence, restarting the chain when any rewriter produces a change.
+
+When any rewriter in the chain produces a non-nothing result, the entire chain
+is restarted with that result as the new input.
+
+# Arguments
+- `rws`: A collection of rewriters to apply
+
+# Examples
+```julia
+julia> r1 = @rule ~x + ~x => 2 * ~x
+julia> r2 = @rule 2 * ~x => ~x * 2
+julia> chain = RestartedChain([r1, r2])
+julia> chain(x + x)  # Applies r1, then restarts and applies r2
+```
+"""
 struct RestartedChain{Cs}
     rws::Cs
 end
@@ -114,6 +203,26 @@ end
 end
 
 
+"""
+    Fixpoint(rw)
+
+Apply a rewriter repeatedly until a fixed point is reached.
+
+The rewriter is applied repeatedly until the output equals the input
+(either by identity or by `isequal`), indicating a fixed point has been reached.
+
+# Arguments
+- `rw`: The rewriter to apply repeatedly
+
+# Examples
+```julia
+julia> r = @rule ~x + ~x => 2 * ~x
+julia> fp = Fixpoint(r)
+julia> fp(x + x + x + x)  # Keeps applying until no more changes
+```
+
+See also: [`FixpointNoCycle`](@ref)
+"""
 struct Fixpoint{C}
     rw::C
 end
@@ -180,14 +289,80 @@ end
 using .Threads
 
 
+"""
+    Postwalk(rw; threaded=false, thread_cutoff=100, maketerm=maketerm)
+
+Apply a rewriter to a symbolic expression tree in post-order (bottom-up).
+
+Post-order traversal visits child nodes before their parents, allowing for
+simplification of subexpressions before the containing expression.
+
+# Arguments
+- `rw`: The rewriter to apply at each node
+- `threaded`: If true, use multi-threading for large expressions
+- `thread_cutoff`: Minimum node count to trigger threading
+- `maketerm`: Function to construct terms (defaults to `maketerm`)
+
+# Examples
+```julia
+julia> r = @rule ~x + ~x => 2 * ~x
+julia> pw = Postwalk(r)
+julia> pw((x + x) * (y + y))  # Simplifies both additions
+2x * 2y
+```
+
+See also: [`Prewalk`](@ref)
+"""
 function Postwalk(rw; threaded::Bool=false, thread_cutoff=100, maketerm=maketerm)
     Walk{:post, typeof(rw), typeof(maketerm), threaded}(rw, thread_cutoff, maketerm)
 end
 
+"""
+    Prewalk(rw; threaded=false, thread_cutoff=100, maketerm=maketerm)
+
+Apply a rewriter to a symbolic expression tree in pre-order (top-down).
+
+Pre-order traversal visits parent nodes before their children, allowing for
+transformation of the overall structure before processing subexpressions.
+
+# Arguments
+- `rw`: The rewriter to apply at each node
+- `threaded`: If true, use multi-threading for large expressions
+- `thread_cutoff`: Minimum node count to trigger threading
+- `maketerm`: Function to construct terms (defaults to `maketerm`)
+
+# Examples
+```julia
+julia> r = @rule sin(~x) => cos(~x)
+julia> pw = Prewalk(r)
+julia> pw(sin(sin(x)))  # Transforms outer sin first
+cos(cos(x))
+```
+
+See also: [`Postwalk`](@ref)
+"""
 function Prewalk(rw; threaded::Bool=false, thread_cutoff=100, maketerm=maketerm)
     Walk{:pre, typeof(rw), typeof(maketerm), threaded}(rw, thread_cutoff, maketerm)
 end
 
+"""
+    PassThrough(rw)
+
+A rewriter that returns the input unchanged if the wrapped rewriter returns `nothing`.
+
+This is useful for making rewriters that preserve the input when no rule applies.
+
+# Arguments
+- `rw`: The rewriter to wrap
+
+# Examples
+```julia
+julia> r = @rule sin(~x) => cos(~x)
+julia> pt = PassThrough(r)
+julia> pt(sin(x))  # Returns cos(x)
+julia> pt(tan(x))  # Returns tan(x) unchanged
+```
+"""
 struct PassThrough{C}
     rw::C
 end