docs: move docstring examples, and de-duplicate

A bunch of docstrings that had text basically identical to the
generic docstring for the operation (e.g. for +, issubset, etc.)
except for an example, were removed. The examples were then put
directly into the relevant .md files with some extra text.

Co-authored-by: Codex <codex@openai.com>

Author: fingolfin

docs/src/CommutativeAlgebra/ModulesOverMultivariateRings/subquotients.md

@@ -308,8 +308,36 @@ zero(M::SubquoModule)
 
 Whether a given element of a subquotient is zero can be tested as follows:
 
-```@docs
-is_zero(m::SubquoModuleElem)
+```jldoctest
+julia> R, (x, y, z) = polynomial_ring(QQ, [:x, :y, :z])
+(Multivariate polynomial ring in 3 variables over QQ, QQMPolyRingElem[x, y, z])
+
+julia> F = free_module(R, 1)
+Free module of rank 1 over R
+
+julia> A = R[x; y]
+[x]
+[y]
+
+julia> B = R[x^2; y^3; z^4]
+[x^2]
+[y^3]
+[z^4]
+
+julia> M = subquotient(F, A, B)
+Subquotient of submodule with 2 generators
+  1: x*e[1]
+  2: y*e[1]
+by submodule with 3 generators
+  1: x^2*e[1]
+  2: y^3*e[1]
+  3: z^4*e[1]
+
+julia> is_zero(M[1])
+false
+
+julia> is_zero(x*M[1])
+true
 ```
 
 In the graded case, we additionally have:
@@ -328,16 +356,98 @@ The functions [`is_graded`](@ref), [`is_standard_graded`](@ref), [`is_z_graded`]
 and [`is_zm_graded`](@ref) carry over analogously to subquotients. They return `true` if the
 respective property is satisfied, and `false` otherwise. In addition, we have:
 
-```@docs
-==(M::SubquoModule{T}, N::SubquoModule{T}) where T
+```jldoctest
+julia> R, (x, y, z) = polynomial_ring(QQ, [:x, :y, :z])
+(Multivariate polynomial ring in 3 variables over QQ, QQMPolyRingElem[x, y, z])
+
+julia> F = free_module(R, 1)
+Free module of rank 1 over R
+
+julia> AM = R[x;]
+[x]
+
+julia> BM = R[x^2; y^3; z^4]
+[x^2]
+[y^3]
+[z^4]
+
+julia> M = subquotient(F, AM, BM)
+Subquotient of submodule with 1 generator
+  1: x*e[1]
+by submodule with 3 generators
+  1: x^2*e[1]
+  2: y^3*e[1]
+  3: z^4*e[1]
+
+julia> AN = R[x; y]
+[x]
+[y]
+
+julia> BN = R[x^2+y^4; y^3; z^4]
+[x^2 + y^4]
+[      y^3]
+[      z^4]
+
+julia> N = subquotient(F, AN, BN)
+Subquotient of submodule with 2 generators
+  1: x*e[1]
+  2: y*e[1]
+by submodule with 3 generators
+  1: (x^2 + y^4)*e[1]
+  2: y^3*e[1]
+  3: z^4*e[1]
+
+julia> is_subset(M, N)
+true
+
+julia> M == N
+false
 ```
 
-```@docs
-is_subset(M::SubquoModule{T}, N::SubquoModule{T}) where T
+```jldoctest
+julia> Rg, (x, y, z) = graded_polynomial_ring(QQ, [:x, :y, :z]);
+
+julia> F = graded_free_module(Rg, 2);
+
+julia> O1 = [x*F[1]+y*F[2], y*F[2]];
+
+julia> O1a = [x*F[1], y*F[2]];
+
+julia> O2 = [x^2*F[1]+y^2*F[2], y^2*F[2]];
+
+julia> M1 = subquotient(F, O1, O2);
+
+julia> M2 = subquotient(F, O1a, O2);
+
+julia> M1 == M2
+true
 ```
 
-```@docs
-is_zero(M::SubquoModule)
+```jldoctest
+julia> R, (x, y, z) = polynomial_ring(QQ, [:x, :y, :z])
+(Multivariate polynomial ring in 3 variables over QQ, QQMPolyRingElem[x, y, z])
+
+julia> F = free_module(R, 1)
+Free module of rank 1 over R
+
+julia> A = R[x^2+y^2;]
+[x^2 + y^2]
+
+julia> B = R[x^2; y^3; z^4]
+[x^2]
+[y^3]
+[z^4]
+
+julia> M = subquotient(F, A, B)
+Subquotient of submodule with 1 generator
+  1: (x^2 + y^2)*e[1]
+by submodule with 3 generators
+  1: x^2*e[1]
+  2: y^3*e[1]
+  3: z^4*e[1]
+
+julia> is_zero(M)
+false
 ```
 
 ## Basic Operations on Subquotients
@@ -423,6 +533,3 @@ degree(a:: SubQuoHom)
 ```@docs
 grading_group(a:: SubQuoHom)
 ```
-
-
-

docs/src/CommutativeAlgebra/affine_algebras.md

@@ -172,8 +172,22 @@ simplify(f::MPolyQuoRingElem)
 
 ### Tests on Elements of Affine Algebras
 
-```@docs
-==(f::MPolyQuoRingElem{T}, g::MPolyQuoRingElem{T}) where T
+Use `f == g` to test whether two elements of an affine algebra represent the
+same class modulo the defining ideal.
+
+```jldoctest
+julia> R, (x,) = polynomial_ring(QQ, [:x]);
+
+julia> A, p = quo(R, ideal(R, [x^4]));
+
+julia> f = p(x-x^6)
+-x^6 + x
+
+julia> g = p(x)
+x
+
+julia> f == g
+true
 ```
 
 ```@docs
@@ -280,21 +294,42 @@ minimal_generating_set(I::MPolyQuoIdeal{<:MPolyDecRingElem})
 
 #### Simple Ideal Operations in Affine Algebras
 
-##### Powers of Ideal
+If `a` and `b` are ideals in an affine algebra `A`, and `m` is a non-negative
+integer, then the standard ideal operations are available:
 
-```@docs
-:^(a::MPolyQuoIdeal, m::Int)
-```
-##### Sum of Ideals
+- `a + b` for sums,
+- `a * b` for products, and
+- `a^m` for powers.
 
-```@docs
-:+(a::MPolyQuoIdeal{T}, b::MPolyQuoIdeal{T}) where T
-```
+The following examples illustrate these operations.
+
+```jldoctest
+julia> R, (x, y) = polynomial_ring(QQ, [:x, :y]);
 
-##### Product of Ideals
+julia> A, _ = quo(R, [x^2-y, y^2-x+y]);
 
-```@docs
-:*(a::MPolyQuoIdeal{T}, b::MPolyQuoIdeal{T}) where T
+julia> a = ideal(A, [x+y])
+Ideal generated by
+  x + y
+
+julia> b = ideal(A, [x^2+y^2, x+y])
+Ideal generated by
+  x^2 + y^2
+  x + y
+
+julia> a+b
+Ideal generated by
+  x + y
+  x^2 + y^2
+
+julia> a*b
+Ideal generated by
+  x^3 + x^2*y + x*y^2 + y^3
+  x^2 + 2*x*y + y^2
+
+julia> a^2
+Ideal generated by
+  x^2 + 2*x*y + y^2
 ```
 
 #### Intersection of Ideals
@@ -321,20 +356,78 @@ With respect to the decomposition of an ideal `Ì` in an  affine algebra, we hav
 
 #### Basic Tests
 
-```@docs
-is_zero(a::MPolyQuoIdeal)
+For ideals in an affine algebra `A`, use `is_zero(a)` to check whether `a` is
+the zero ideal.
+
+```jldoctest
+julia> R, (x, y) = polynomial_ring(QQ, [:x, :y]);
+
+julia> A, _ = quo(R, [x^2-y, y^2-x+y]);
+
+julia> a = ideal(A, [x^2+y^2, x+y])
+Ideal generated by
+  x^2 + y^2
+  x + y
+
+julia> is_zero(a)
+false
+
+julia> b = ideal(A, [x^2-y])
+Ideal generated by
+  x^2 - y
+
+julia> is_zero(b)
+true
 ```
 
 #### Containment of Ideals in Affine Algebras
 
-```@docs
-is_subset(a::MPolyQuoIdeal{T}, b::MPolyQuoIdeal{T}) where T
+Use `is_subset(a, b)` to test whether an ideal `a` is contained in another
+ideal `b`.
+
+```jldoctest
+julia> R, (x, y) = polynomial_ring(QQ, [:x, :y]);
+
+julia> A, _ = quo(R, ideal(R, [x^3*y^2-y^3*x^2, x*y^4-x*y^2]));
+
+julia> a = ideal(A, [x^3*y^4-x+y, x*y+y^2*x])
+Ideal generated by
+  x^3*y^4 - x + y
+  x*y^2 + x*y
+
+julia> b = ideal(A, [x^3*y^3-x+y, x^2*y+y^2*x])
+Ideal generated by
+  x^3*y^3 - x + y
+  x^2*y + x*y^2
+
+julia> is_subset(a, b)
+false
+
+julia> is_subset(b, a)
+true
 ```
 
 #### Equality of Ideals in Affine Algebras
 
-```@docs
-==(a::MPolyQuoIdeal{T}, b::MPolyQuoIdeal{T}) where T
+Use `a == b` to test equality of ideals.
+
+```jldoctest
+julia> R, (x, y) = polynomial_ring(QQ, [:x, :y]);
+
+julia> A, _ = quo(R, ideal(R, [x^3*y^2-y^3*x^2, x*y^4-x*y^2]));
+
+julia> a = ideal(A, [x^3*y^4-x+y, x*y+y^2*x])
+Ideal generated by
+  x^3*y^4 - x + y
+  x*y^2 + x*y
+
+julia> b = ideal(A, [x^3*y^3-x+y, x^2*y+y^2*x])
+Ideal generated by
+  x^3*y^3 - x + y
+  x^2*y + x*y^2
+
+julia> a == b
+false
 ```
 
 #### Ideal Membership