Add docstrings

Author: blegat

src/comparison.jl

@@ -330,24 +330,62 @@ _not_first_indices(n, ::Type{Graded{M}}) where {M} = _not_first_indices(n, M)
 """
     struct ExponentsIterator{M}(
         object;
-        min_deg::Int = 0,
-        max_deg::Union{Nothing,Int} = nothing,
+        mindegree::Int = 0,
+        maxdegree::Union{Nothing,Int} = nothing,
         inline::Bool = false,
     )
 
 An iterator for generating monomial exponents for monomial
 ordering `M`. The type of the vector of exponents is the type of
 `object` and is length (i.e., the number of variables) is `length(object)`.
+
+See also [`monomials`](@ref).
+
+### Examples
+
+The following example shows how to generate all exponents of
+monomials of 2 variables up to degree 2.
+```jldoctest
+julia> collect(ExponentsIterator((0, 0), maxdegree = 2))
+6-element Vector{Tuple{Int64, Int64}}:
+ (0, 0)
+ (0, 1)
+ (1, 0)
+ (0, 2)
+ (1, 1)
+ (2, 0)
+```
+Note that you can easily generate the tuple of exponents
+of arbitrary length using `ntuple` as follows:
+```jldoctest
+julia> collect(ExponentsIterator(ntuple(zero, 3), mindegree = 2, maxdegree = 2))
+6-element Vector{Tuple{Int64, Int64, Int64}}:
+ (0, 0, 2)
+ (0, 1, 1)
+ (0, 2, 0)
+ (1, 0, 1)
+ (1, 1, 0)
+ (2, 0, 0)
+```
+You can also change the monomial ordering as follows:
+```jldoctest
+julia> collect(Iterators.take(ExponentsIterator{LexOrder}(zeros(Int, 2), mindegree = 2, maxdegree = 4), 4))
+4-element Vector{Vector{Int64}}:
+ [0, 2]
+ [0, 3]
+ [0, 4]
+ [1, 0]
+```
 """
 struct ExponentsIterator{M,D<:Union{Nothing,Int},O}
     object::O # Used to get number of variables and get new zero elements
-    min_deg::Int
-    max_deg::D
+    mindegree::Int
+    maxdegree::D
     inline::Bool
 end
 
-function ExponentsIterator{M}(object; min_deg::Int = 0, max_deg::Union{Nothing,Int} = nothing, inline::Bool = false) where {M}
-    ExponentsIterator{M,typeof(max_deg),typeof(object)}(object, min_deg, max_deg, inline)
+function ExponentsIterator{M}(object; mindegree::Int = 0, maxdegree::Union{Nothing,Int} = nothing, inline::Bool = false) where {M}
+    ExponentsIterator{M,typeof(maxdegree),typeof(object)}(object, mindegree, maxdegree, inline)
 end
 
 function ExponentsIterator(args...; kws...)
@@ -359,9 +397,9 @@ Base.IteratorSize(::Type{<:ExponentsIterator{M,Nothing}}) where {M} = Base.IsInf
 Base.IteratorSize(::Type{<:ExponentsIterator{M,Int}}) where {M} = Base.HasLength()
 
 function Base.length(it::ExponentsIterator{M,Int}) where {M}
-    len = binomial(nvariables(it) + it.max_deg, nvariables(it))
-    if it.min_deg > 0
-        len -= binomial(nvariables(it) + it.min_deg, nvariables(it))
+    len = binomial(nvariables(it) + it.maxdegree, nvariables(it))
+    if it.mindegree > 0
+        len -= binomial(nvariables(it) + it.mindegree - 1, nvariables(it))
     end
     return len
 end
@@ -371,14 +409,14 @@ nvariables(it::ExponentsIterator) = length(it.object)
 _increase_degree(it::ExponentsIterator{<:Graded,Nothing}, _) = false
 _increase_degree(it::ExponentsIterator{<:Graded,Int}, _) = false
 _increase_degree(it::ExponentsIterator{M,Nothing}, _) where {M} = true
-_increase_degree(it::ExponentsIterator{M,Int}, deg) where {M} = deg < it.max_deg
+_increase_degree(it::ExponentsIterator{M,Int}, deg) where {M} = deg < it.maxdegree
 
 # We just changed the degree by removing `Δ`,
 # In graded ordering, we just add `Δ` to maintain the same degree
 _adjust_degree(::ExponentsIterator{<:Graded}, _, Δ) = Δ
-# Otherwise, we just need the degree to stay above `it.min_deg`,
-# so we need to add `it.min_deg - deg`
-_adjust_degree(it::ExponentsIterator, deg, _) = min(0, it.min_deg - deg)
+# Otherwise, we just need the degree to stay above `it.mindegree`,
+# so we need to add `it.mindegree - deg`
+_adjust_degree(it::ExponentsIterator, deg, _) = min(0, it.mindegree - deg)
 
 _setindex!(x, v, i) = Base.setindex!(x, v, i)
 _setindex!(x::Tuple, v, i) = Base.setindex(x, v, i)
@@ -401,7 +439,7 @@ function _iterate!(it::ExponentsIterator{M}, z, deg) where {M}
     I = _not_first_indices(nvariables(it), M)
     i = findfirst(i -> !iszero(z[i]), I)
     if isnothing(i)
-        if !isnothing(it.max_deg) && deg == it.max_deg
+        if !isnothing(it.maxdegree) && deg == it.maxdegree
             return
         end
         z = _zero!(z)
@@ -410,7 +448,7 @@ function _iterate!(it::ExponentsIterator{M}, z, deg) where {M}
     end
     j = I[i]
     Δ = z[j] - 1
-    _setindex!(z, 0, j)
+    z = _setindex!(z, 0, j)
     deg -= Δ
     Δ = _adjust_degree(it, deg, Δ)
     deg += Δ
@@ -424,8 +462,8 @@ function Base.iterate(it::ExponentsIterator{M}) where {M}
         return
     end
     z = _zero(it.object)
-    z = _setindex!(z, it.min_deg, _last_lex_index(nvariables(it), M))
-    return z, (z, it.min_deg)
+    z = _setindex!(z, it.mindegree, _last_lex_index(nvariables(it), M))
+    return z, (z, it.mindegree)
 end
 
 function Base.iterate(it::ExponentsIterator, state)

src/polynomial.jl

@@ -252,10 +252,12 @@ end
 
 Returns an iterator over the monomials of `p` of the nonzero terms of the polynomial sorted in the decreasing order.
 
-    monomials(vars::Tuple, degs::AbstractVector{Int}, filter::Function = m -> true)
+    monomials(vars::Union{Vector{<:AbstractVariable},Tuple}, degs::AbstractVector{Int}, filter::Function = m -> true)
 
 Builds the vector of all the monomial_vector `m` with variables `vars` such that the degree `degree(m)` is in `degs` and `filter(m)` is `true`.
 
+See also [`ExponentsIterator`](@ref).
+
 ### Examples
 
 Calling `monomials` on ``4x^2y + xy + 2x`` should return an iterator of ``[x^2y, xy, x]``.