From 33ce32b6304e22a59f0df54484bb75be93e94dec Mon Sep 17 00:00:00 2001
From: Aayush Sabharwal <aayush.sabharwal@juliahub.com>
Date: Mon, 25 Mar 2024 15:03:46 +0530
Subject: [PATCH] docs: add docs for fixpoint_sub and fast_substitute

---
 docs/src/manual/expression_manipulation.md |  2 ++
 src/variable.jl                            | 21 +++++++++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/docs/src/manual/expression_manipulation.md b/docs/src/manual/expression_manipulation.md
index 3dfbbd44b..102aa985c 100644
--- a/docs/src/manual/expression_manipulation.md
+++ b/docs/src/manual/expression_manipulation.md
@@ -31,4 +31,6 @@ Symbolics.coeff
 Symbolics.replace
 Symbolics.occursin
 Symbolics.filterchildren
+Symbolics.fixpoint_sub
+Symbolics.fast_substitute
 ```
diff --git a/src/variable.jl b/src/variable.jl
index e4b0eaf42..d2b461d80 100644
--- a/src/variable.jl
+++ b/src/variable.jl
@@ -414,6 +414,17 @@ function SymbolicIndexingInterface.symbolic_evaluate(ex::Union{Num, Arr, Symboli
     fixpoint_sub(ex, d; kwargs...)
 end
 
+"""
+    fixpoint_sub(expr, dict; operator = Nothing)
+
+Given a symbolic expression, equation or inequality `expr` perform the substitutions in
+`dict` recursively until the expression does not change. Substitutions that depend on one
+another will thus be recursively expanded. For example,
+`fixpoint_sub(x, Dict(x => y, y => 3))` will return `3`. The `operator` keyword can be
+specified to prevent substitution of expressions inside operators of the given type.
+
+See also: [`fast_substitute`](@ref).
+"""
 function fixpoint_sub(x, dict; operator = Nothing)
     y = fast_substitute(x, dict; operator)
     while !isequal(x, y)
@@ -425,6 +436,16 @@ function fixpoint_sub(x, dict; operator = Nothing)
 end
 
 const Eq = Union{Equation, Inequality}
+"""
+    fast_substitute(expr, dict; operator = Nothing)
+
+Given a symbolic expression, equation or inequality `expr` perform the substitutions in
+`dict`. This only performs the substitutions once. For example,
+`fast_substitute(x, Dict(x => y, y => 3))` will return `y`. The `operator` keyword can be
+specified to prevent substitution of expressions inside operators of the given type.
+
+See also: [`fixpoint_sub`](@ref).
+"""
 function fast_substitute(eq::Eq, subs; operator = Nothing)
     if eq isa Inequality
         Inequality(fast_substitute(eq.lhs, subs; operator),