From d56925e474354f44ff7cdd8a1a9c67af50ee61be Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Beno=C3=AEt=20Legat?= <benoit.legat@gmail.com>
Date: Thu, 2 May 2024 17:20:56 +0200
Subject: [PATCH] Improve docs for division

---
 docs/src/division.md | 35 ++++++++++++++++++++++++++++---
 src/division.jl      | 49 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+), 3 deletions(-)

diff --git a/docs/src/division.md b/docs/src/division.md
index 19fd76ce..d126550b 100644
--- a/docs/src/division.md
+++ b/docs/src/division.md
@@ -1,7 +1,5 @@
 # Division
 
-The `gcd` and `lcm` functions of `Base` have been implemented for monomials, you have for example `gcd(x^2*y^7*z^3, x^4*y^5*z^2)` returning `x^2*y^5*z^2` and `lcm(x^2*y^7*z^3, x^4*y^5*z^2)` returning `x^4*y^7*z^3`.
-
 Given two polynomials, ``p`` and ``d``, there are unique ``r`` and ``q`` such that ``p = q d + r`` and the leading term of ``d`` does not divide the leading term of ``r``.
 You can obtain ``q`` using the `div` function and ``r`` using the `rem` function.
 The `divrem` function returns ``(q, r)``.
@@ -9,10 +7,41 @@ The `divrem` function returns ``(q, r)``.
 Given a polynomial ``p`` and divisors ``d_1, \ldots, d_n``, one can find ``r`` and ``q_1, \ldots, q_n`` such that ``p = q_1 d_1 + \cdots + q_n d_n + r`` and none of the leading terms of ``q_1, \ldots, q_n`` divide the leading term of ``r``.
 You can obtain the vector ``[q_1, \ldots, q_n]`` using `div(p, d)` where ``d = [d_1, \ldots, d_n]`` and ``r`` using the `rem` function with the same arguments.
 The `divrem` function returns ``(q, r)``.
-
 ```@docs
+divrem
+div
+rem
 divides
 div_multiple
+```
+
+Note that the coefficients of the polynomials need to be a field for `div`,
+`rem` and `divrem` to work.
+Alternatively, [`pseudo_rem`](@ref) or [`pseudo_divrem`](@ref) can be used
+instead as they do not require the coefficient type to be a field.
+```@docs
 pseudo_rem
+pseudo_divrem
 rem_or_pseudo_rem
 ```
+
+## Greatest Common Divisor (GCD)
+
+The Greatest Common Divisor (GCD) and Least Common Multiple (LCM) can be
+obtained for integers respectively with the `gcd` and `lcm` functions.
+The same functions can be used with monomials and polynomials:
+```@docs
+gcd
+AbstractUnivariateGCDAlgorithm
+GeneralizedEuclideanAlgorithm
+SubresultantAlgorithm
+```
+Internal functions of the `gcd` algorithm:
+```@docs
+isolate_variable
+primitive_univariate_gcd!
+univariate_gcd
+content
+primitive_part
+primitive_part_content
+```
diff --git a/src/division.jl b/src/division.jl
index feedeb47..889064b9 100644
--- a/src/division.jl
+++ b/src/division.jl
@@ -26,9 +26,36 @@ function divides(t1::AbstractTermLike, t2::AbstractTermLike)
 end
 divides(t1::AbstractVariable, t2::AbstractVariable) = t1 == t2
 
+"""
+    gcd(m1::AbstractMonomialLike, m2::AbstractMonomialLike)
+
+Return the largest monomial `m` such that both `divides(m, m1)`
+and `divides(m, m2)` are `true`.
+
+```@example
+julia> @polyvar x y z;
+
+julia> gcd(x^2*y^7*z^3, x^4*y^5*z^2)
+x²y⁵z²
+```
+"""
 function Base.gcd(m1::AbstractMonomialLike, m2::AbstractMonomialLike)
     return map_exponents(min, m1, m2)
 end
+
+"""
+    lcm(m1::AbstractMonomialLike, m2::AbstractMonomialLike)
+
+Return the smallest monomial `m` such that both `divides(m1, m)`
+and `divides(m2, m)` are `true`.
+
+```@example
+julia> @polyvar x y z;
+
+julia> lcm(x^2*y^7*z^3, x^4*y^5*z^2)
+x^4*y^7*z^3
+```
+"""
 function Base.lcm(m1::AbstractMonomialLike, m2::AbstractMonomialLike)
     return map_exponents(max, m1, m2)
 end
@@ -152,6 +179,26 @@ function Base.rem(f::_APL, g::Union{_APL,AbstractVector{<:_APL}}; kwargs...)
     return divrem(f, g; kwargs...)[2]
 end
 
+"""
+    pseudo_divrem(f::_APL{S}, g::_APL{T}, algo) where {S,T}
+
+Return the pseudo divisor and remainder of `f` modulo `g` as defined in [Knu14, Algorithm R, p. 425].
+
+When the coefficient type is not a field, it is not always possible to carry a
+division. For instance, the division of `f = 3x + 1` by `g = 2x + 1` cannot be done over
+integers. On the other hand, one can write `2f = 3g - 1`.
+In general, the *pseudo* division of `f` by `g` is:
+```math
+l f(x) = q(x) g(x) + r(x)
+```
+where `l` is a power of the leading coefficient of `g` some constant.
+
+See also [`pseudo_rem`](@ref).
+
+[Knu14] Knuth, D.E., 2014.
+*Art of computer programming, volume 2: Seminumerical algorithms.*
+Addison-Wesley Professional. Third edition.
+"""
 function pseudo_divrem(f::_APL{S}, g::_APL{T}, algo) where {S,T}
     return _pseudo_divrem(
         algebraic_structure(MA.promote_operation(-, S, T)),
@@ -189,6 +236,8 @@ end
 
 Return the pseudo remainder of `f` modulo `g` as defined in [Knu14, Algorithm R, p. 425].
 
+See [`pseudo_divrem`](@ref) for more details.
+
 [Knu14] Knuth, D.E., 2014.
 *Art of computer programming, volume 2: Seminumerical algorithms.*
 Addison-Wesley Professional. Third edition.