From 02884f30c48a6b23087a80ae10356c0a6fa73fb3 Mon Sep 17 00:00:00 2001
From: Max Horn <max@quendi.de>
Date: Wed, 13 Sep 2023 16:37:18 +0200
Subject: [PATCH] Add docstrings for various map construction functions (#1431)

Also include jldoctests for each, and fix a bug in the
printing of IdentityMap instances.
---
 docs/src/functional_map.md | 17 +------------
 docs/src/map_interface.md  | 12 ++++-----
 src/Map.jl                 | 52 ++++++++++++++++++++++++++++++++++++++
 src/generic/Map.jl         |  2 +-
 4 files changed, 60 insertions(+), 23 deletions(-)

diff --git a/docs/src/functional_map.md b/docs/src/functional_map.md
index 0a6e00f814..4cbd718055 100644
--- a/docs/src/functional_map.md
+++ b/docs/src/functional_map.md
@@ -51,21 +51,6 @@ a Julia function/closure implementing the map.
 
 Such maps can be constructed using the following function:
 
-```julia
+```@docs
 map_from_func(f::Function, R, S)
 ```
-
-Construct the generic functional map with domain and codomain given by the parent objects
-$R$ and $S$ corresponding to the Julia function $f$.
-
-**Examples**
-
-```jldoctest
-julia> f = map_from_func(x -> x + 1, ZZ, ZZ)
-Map defined by a Julia function
-  from integers
-  to integers
-
-julia> f(ZZ(2))
-3
-```
diff --git a/docs/src/map_interface.md b/docs/src/map_interface.md
index 33e157a087..eff40a8d7b 100644
--- a/docs/src/map_interface.md
+++ b/docs/src/map_interface.md
@@ -1,6 +1,8 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = :(using AbstractAlgebra)
+DocTestSetup = quote
+    using AbstractAlgebra
+end
 ```
 
 # Map Interface
@@ -166,7 +168,7 @@ map are identity maps on the same domain.
 To construct an identity map for a given domain, specified by a parent object `R`, say,
 we have the following function.
 
-```julia
+```@docs
 identity_map(R::Set)
 ```
 
@@ -189,12 +191,10 @@ should be applied.
 
 To construct a composition map from two existing maps, we have the following function:
 
-```julia
-compose(f::Map{D, U}, g::Map{U, C}) where {D, U, C}
+```@docs
+compose(f::Map, g::Map)
 ```
 
-Compose the two maps $f$ and $g$, i.e. return the map $h$ such that $h(x) = g(f(x))$.
-
 As a shortcut for this function we have the following operator:
 
 ```julia
diff --git a/src/Map.jl b/src/Map.jl
index 111ad7914e..3d7b95c4f5 100644
--- a/src/Map.jl
+++ b/src/Map.jl
@@ -27,6 +27,23 @@ end
 #
 ###############################################################################
 
+@doc raw"""
+    compose(f::Map, g::Map)
+
+Compose the two maps $f$ and $g$, i.e. return the map $h$ such that $h(x) = g(f(x))$.
+
+# Examples
+```jldoctest; setup = :(using AbstractAlgebra)
+julia> f = map_from_func(x -> x + 1, ZZ, ZZ);
+
+julia> g = map_from_func(x -> QQ(x), ZZ, QQ);
+
+julia> h = compose(f, g)
+Functional composite map
+  first map: integers -> integers
+  next map: integers -> rationals
+```
+"""
 function compose(f::Map, g::Map)
    check_composable(f, g)
    return Generic.CompositeMap(f, g)
@@ -40,6 +57,24 @@ end
 #
 ################################################################################
 
+@doc raw"""
+    identity_map(R::D) where D <: AbstractAlgebra.Set
+
+Return an identity map on the domain $R$.
+
+# Examples
+```jldoctest; setup = :(using AbstractAlgebra)
+julia> R, t = ZZ[:t]
+(Univariate polynomial ring in t over integers, t)
+
+julia> f = identity_map(R)
+Identity map
+  of univariate polynomial ring in t over integers
+
+julia> f(t)
+t
+```
+"""
 identity_map(R::D) where D <: AbstractAlgebra.Set = Generic.IdentityMap{D}(R)
 
 ################################################################################
@@ -48,6 +83,23 @@ identity_map(R::D) where D <: AbstractAlgebra.Set = Generic.IdentityMap{D}(R)
 #
 ################################################################################
 
+@doc raw"""
+    map_from_func(image_fn::Function, domain, codomain)
+
+Construct the generic functional map with domain and codomain given by the parent objects
+$R$ and $S$ corresponding to the Julia function $f$.
+
+# Examples
+```jldoctest; setup = :(using AbstractAlgebra)
+julia> f = map_from_func(x -> x + 1, ZZ, ZZ)
+Map defined by a Julia function
+  from integers
+  to integers
+
+julia> f(ZZ(2))
+3
+```
+"""
 function map_from_func(image_fn::Function, domain, codomain)
    return Generic.FunctionalMap(domain, codomain, image_fn)
 end
diff --git a/src/generic/Map.jl b/src/generic/Map.jl
index f0c5531f57..3a0446fd9a 100644
--- a/src/generic/Map.jl
+++ b/src/generic/Map.jl
@@ -62,7 +62,7 @@ codomain(f::IdentityMap) = f.domain
 
 function show(io::IO, ::MIME"text/plain", M::IdentityMap)
    io = pretty(io)
-   println("Identity map")
+   println(io, "Identity map")
    print(io, Indent(), "of ", Lowercase())
    show(io, MIME("text/plain"), domain(M))
    print(io, Dedent())