docs: add more docstrings, fix broken links

Author: AayushSabharwal

docs/src/manual/variants.md

@@ -9,7 +9,7 @@ as `BasicSymbolic`. A `BasicSymbolic` is considered immutable. Mutating its fiel
 behavior.
 
 In SymbolicUtils v3, the type `T` in `BasicSymbolic{T}` was the type represented by the symbolic
-variable. In other words, `T` was the [`symtype`](@ref) of the variable.
+variable. In other words, `T` was the [`SymbolicUtils.symtype`](@ref) of the variable.
 
 In SymbolicUtils v4, the `symtype` is not stored in the type, and is instead a field of the
 struct. This allows for greatly increased type-stability. The type `T` in `BasicSymbolic{T}`
@@ -26,6 +26,7 @@ A given expression must be pure in its `vartype`. In other words, no operation s
 of different `vartype`s.
 
 !!! warning "A short note on (im-)mutability"
+  
   While `ismutabletype(BasicSymbolic)` returns `true`, symbolic types are IMMUTABLE.
   Any mutation is undefined behavior and can lead to very confusing and hard-to-debug issues.
   This includes internal mutation, such as mutating `AddMul.dict`. The arrays returned from
@@ -294,6 +295,7 @@ range of indices over which they should iterate, in case such a range is explici
 provided.
 
 !!! note
+  
   The common global index variable is printed as `_1`, `_2`, ... in arrayops. It is not
   a valid symbolic variable outside of an `ArrayOp`'s `expr`.
 
@@ -336,8 +338,8 @@ to Base-like behavior:
   doing so requires the function(s) passed to `map` and `mapreduce` instead of their types
   or shapes.
 - Since `ndims` information is not present in the type, `eachindex`, `iterate`, `size`,
-  `axes`, `ndims`, `collect` are type-unstable. [`stable_eachindex`](@ref) is useful as
-  a type-stable iteration alternative.
+  `axes`, `ndims`, `collect` are type-unstable. [`SymbolicUtils.stable_eachindex`](@ref) is
+  useful as a type-stable iteration alternative.
 - `ifelse` requires that both the true and false cases have identical shape.
 - Symbolic arrays _only_ support cartesian indexing. For example, given `@syms x[1:3, 1:3]`
   accessing `x[4]` is invalid and `x[1, 2]` should be used. Valid indices are
@@ -385,7 +387,7 @@ words,
 Here, `f1(x)` is considered a symbolic function `f1` called with the argument `x` and
 `f2(x)` is considered a dependent variable that depends on `x`. The utilities
 [`SymbolicUtils.is_function_symbolic`](@ref), [`SymbolicUtils.is_function_symtype`](@ref),
-[`symbolicUtils.is_called_function_symbolic`](@ref) can be used to differentiate between
+[`SymbolicUtils.is_called_function_symbolic`](@ref) can be used to differentiate between
 these cases.
 
 ## API

src/SymbolicUtils.jl

@@ -18,8 +18,7 @@ using SymbolicIndexingInterface
 import Base: +, -, *, /, //, \, ^, ImmutableDict
 using ConstructionBase
 using TermInterface
-import TermInterface: iscall, isexpr, children,
-                      operation, arguments, metadata, maketerm, sorted_arguments
+import TermInterface: iscall, operation, arguments, metadata, maketerm, sorted_arguments
 # For ReverseDiffExt
 import ArrayInterface
 import ExproniconLite as EL

src/inspect.jl

@@ -33,7 +33,7 @@ the expression.
 This function is used internally for printing via AbstractTrees.
 """
 function AbstractTrees.children(x::BasicSymbolic)
-    iscall(x) ? sorted_arguments(x) : isexpr(x) ? sorted_children(x) : ()
+    iscall(x) ? sorted_arguments(x) : ()
 end
 
 """

src/types.jl

@@ -1,8 +1,27 @@
 export SymReal, SafeReal, TreeReal, vartype
 
 abstract type SymVariant end
+"""
+    $TYPEDEF
+
+One of three possible values of the [`vartype`](@ref). This variant is the default and
+behaves as a typical ideal scalar algebra would be expected to.
+"""
 abstract type SymReal <: SymVariant end
+"""
+    $TYPEDEF
+
+One of three possible values of the [`vartype`](@ref). This variant is identical to
+[`SymReal`](@ref) except common terms in the numerator and denominator of a division are
+not cancelled out.
+"""
 abstract type SafeReal <: SymVariant end
+"""
+    $TYPEDEF
+
+One of three possible values of the [`vartype`](@ref). This variant does not assume anything
+about the algebra and always uses the default tree form for expressions.
+"""
 abstract type TreeReal <: SymVariant end
 
 ###
@@ -35,10 +54,25 @@ end
 
 const SCALARS = [Bool, Int, Int32, BigInt, Float64, Float32, BigFloat, Rational{Int}, Rational{Int32}, Rational{BigInt}, ComplexF32, ComplexF64, Complex{BigFloat}]
 
+"""
+    $TYPEDEF
 
+Type of metadata field for symbolics.
+"""
 const MetadataT = Union{Base.ImmutableDict{DataType, Any}, Nothing}
+"""
+    $TYPEDEF
+
+A custom vector type which does not allocate for small numbers of elements. If the number of elements is
+known at compile time, it should be passed as a `Tuple` to the constructor.
+"""
 const SmallV{T} = SmallVec{T, Vector{T}}
 const ShapeVecT = SmallV{UnitRange{Int}}
+"""
+    $TYPEDEF
+
+Type that represents the [`SymbolicUtils.shape`](@ref) of symbolics.
+"""
 const ShapeT = Union{Unknown, ShapeVecT}
 const IdentT = Union{IDType, Nothing}
 const MonomialOrder = MP.Graded{MP.Reverse{MP.InverseLexOrder}}
@@ -50,6 +84,11 @@ const _PolynomialT{T} = DP.Polynomial{PolyVarOrder, MonomialOrder, T}
 # we can't actually print a zero polynomial of this type, since it attempts to call
 # `zero(Any)` but that doesn't matter because we shouldn't ever store a zero polynomial
 const PolynomialT = _PolynomialT{PolyCoeffT}
+"""
+    $TYPEDEF
+
+Allowed types for the [`SymbolicUtils.symtype`](@ref) of symbolics.
+"""
 const TypeT = DataType
 const MonomialT = DP.Monomial{PolyVarOrder, MonomialOrder}
 const MonomialVecT = DP.MonomialVector{PolyVarOrder, MonomialOrder}
@@ -81,6 +120,12 @@ function onepoly()
     PolynomialT(PolyCoeffT[1], mv)
 end
 
+"""
+    $(TYPEDEF)
+
+An EnumX.jl enum used to distinguish between addition and multiplication in
+[`SymbolicUtils.BSImpl.AddMul`](@ref).
+"""
 @enumx AddMulVariant::Bool begin
     ADD
     MUL
@@ -89,7 +134,7 @@ end
 """
     $(TYPEDEF)
 
-Core ADT for `BasicSymbolic`
+Core ADT for symbolic expressions.
 """
 @data mutable BasicSymbolicImpl{T <: SymVariant} begin 
     struct Const
@@ -171,12 +216,38 @@ Core ADT for `BasicSymbolic`
     end
 end
 
+"""
+    Alias for `SymbolicUtils.BasicSymbolicImpl`.
+"""
 const BSImpl = BasicSymbolicImpl
+"""
+    Alias for `SymbolicUtils.BasicSymbolicImpl.Type`.
+"""
 const BasicSymbolic = BSImpl.Type
+"""
+    The type of a mutable buffer containing symbolic arguments. Passing this to the
+    [`SymbolicUtils.Term`](@ref) constructor will avoid allocating a new array.
+"""
 const ArgsT{T} = SmallV{BasicSymbolic{T}}
+"""
+    The type of a read-only buffer containing symbolic arguments. Passing this to the
+    [`SymbolicUtils.Term`](@ref) constructor will avoid allocating a new array. This is
+    the type returned from [`TermInterface.arguments`](@ref).
+"""
 const ROArgsT{T} = ReadOnlyVector{BasicSymbolic{T}, ArgsT{T}}
+"""
+    The type of the dictionary stored in [`BSImpl.AddMul`](@ref). Passing this to the
+    [`SymbolicUtils.Add`](@ref) or [`SymbolicUtils.Mul`](@ref) constructors will avoid
+    allocating a new dictionary.
+"""
 const ACDict{T} = Dict{BasicSymbolic{T}, Number}
+"""
+    The type of the `output_idxs` field in [`BSImpl.ArrayOp`](@ref).
+"""
 const OutIdxT{T} = SmallV{Union{Int, BasicSymbolic{T}}}
+"""
+    The type of the `ranges` field in [`BSImpl.ArrayOp`](@ref).
+"""
 const RangesT{T} = Dict{BasicSymbolic{T}, StepRange{Int, Int}}
 
 """
@@ -423,7 +494,7 @@ end
 ###
 
 """
-    operation(expr)
+    $TYPEDSIGNATURES
 
 Extract the operation (function) from a symbolic function call expression.
 Only valid for expressions where `iscall(expr)` returns `true`.
@@ -454,7 +525,7 @@ operation(expr4)    # returns sin
 operation(arguments(expr4)[1])  # returns +
 ```
 
-See also: [`iscall`](@ref), [`arguments`](@ref)
+See also: [`TermInterface.iscall`](@ref), [`arguments`](@ref)
 """
 @inline function TermInterface.operation(x::BSImpl.Type{T}) where {T}
     @nospecialize x
@@ -612,21 +683,6 @@ end
 """
     $TYPEDSIGNATURES
 
-Check if a `BasicSymbolic` is an expression (not a `Sym` or `Const`).
-
-# Arguments
-- `s`: A `BasicSymbolic` value to check.
-
-# Returns
-`true` if `s` is a compound expression.
-"""
-function isexpr(s::BSImpl.Type)
-    !MData.isa_variant(s, BSImpl.Sym) && !MData.isa_variant(s, BSImpl.Const)
-end
-
-"""
-    iscall(expr)
-
 Check if a symbolic expression `expr` represents a function call. Returns `true` if the 
 expression is a composite expression with an operation and arguments, `false` otherwise.
 
@@ -653,7 +709,9 @@ iscall(x * y)       # true
 
 See also: [`operation`](@ref), [`arguments`](@ref)
 """
-iscall(s::BSImpl.Type) = isexpr(s)
+function TermInterface.iscall(s::BSImpl.Type)
+    !MData.isa_variant(s, BSImpl.Sym) && !MData.isa_variant(s, BSImpl.Const)
+end
 
 """
     $TYPEDSIGNATURES
@@ -2690,9 +2748,9 @@ end
 ###
 
 """
-    promote_symtype(f, Ts...)
+    $TYPEDSIGNATURES
 
-The result of applying `f` to arguments of [`symtype`](#symtype) `Ts...`
+The result of applying `f` to arguments of [`SymbolicUtils.symtype`](@ref) `Ts...`
 
 ```julia
 julia> promote_symtype(+, Real, Real)
@@ -2708,15 +2766,22 @@ julia> promote_symtype(f, Number)
 Complex
 ```
 
-When constructing [`Term`](#Term)s without an explicit symtype,
+When constructing expressions without an explicit symtype,
 `promote_symtype` is used to figure out the symtype of the Term.
+
+It is recommended that all type arguments be annotated with [`SymbolicUtils.TypeT`](@ref)
+and one method be implemented for any combination of `f` and the number of arguments. For
+example, one method is implemented for unary `-` and one method for binary `-`. Each method
+has an `if..elseif` chain to handle possible types. Any call to `promote_type` should be
+typeasserted with `::TypeT`.
 """
 promote_symtype(f, Ts...) = Any
 
 """
     promote_shape(f, shs::ShapeT...)
 
 The shape of the result of applying `f` to arguments of [`shape`](@ref) `shs...`.
+It is recommended that implemented methods `@nospecialize` all the shape arguments.
 """
 promote_shape(f, szs::ShapeT...) = Unknown(-1)
 
@@ -2956,6 +3021,12 @@ Base.empty!(awb::AddWorkerBuffer) = empty!(awb.dict)
 const SYMREAL_ADDBUFFER = TaskLocalValue{AddWorkerBuffer{SymReal}}(AddWorkerBuffer{SymReal})
 const SAFEREAL_ADDBUFFER = TaskLocalValue{AddWorkerBuffer{SafeReal}}(AddWorkerBuffer{SafeReal})
 
+"""
+    $METHODLIST
+
+Add an indexable list or tuple of terms `terms` with the given vartype. Applicable only for
+symbolic expressions with numeric or array of numeric symtype.
+"""
 add_worker(::Type{SymReal}, terms) = SYMREAL_ADDBUFFER[](terms)
 add_worker(::Type{SafeReal}, terms) = SAFEREAL_ADDBUFFER[](terms)
 
@@ -3428,6 +3499,12 @@ function (mwb::MulWorkerBuffer{T})(terms) where {T}
     return Term{T}(*, new_arrterms; type, shape = newshape)
 end
 
+"""
+    $METHODLIST
+
+Multiply an indexable list or tuple of terms `terms` with the given vartype. Applicable
+only for symbolic expressions with numeric or array of numeric symtype.
+"""
 mul_worker(::Type{SymReal}, terms) = SYMREAL_MULBUFFER[](terms)
 mul_worker(::Type{SafeReal}, terms) = SAFEREAL_MULBUFFER[](terms)