Add docstrings for various map construction functions

[fingolfin]

Also include jldoctests for each, and fix a bug in the printing of IdentityMap instances.

[codecov]

Codecov Report

Merging #1431 (7812899) into master (15764fd) will increase coverage by 2.52%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           master    #1431      +/-   ##
==========================================
+ Coverage   82.05%   84.58%   +2.52%     
==========================================
  Files         108      109       +1     
  Lines       26777    29363    +2586     
==========================================
+ Hits        21973    24837    +2864     
+ Misses       4804     4526     -278     

Files Changed	Coverage Δ
src/Map.jl	100.00% <ø> (ø)
src/generic/Map.jl	68.46% <100.00%> (+26.95%)	⬆️

... and 82 files with indirect coverage changes

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[fingolfin]

Doctests still fail so I probably made another mistake. I'll work on it later

[thofma]

Documenter is again maximally useless when reporting the error

[fingolfin]

So I've used the advanced debugging technique of inserting println statements into the Documenter code to learn that this line is causing the problems (or at least it is the first one I am hitting right now).

Documenter first runs this code successfully:

            c = IOCapture.capture(rethrow = InterruptException) do
                Core.eval(sandbox, ex)
            end

where ex is equal to the following quoted code:

begin
    $(Expr(:softscope, true))
    f = AbstractAlgebra.identity_map(AbstractAlgebra.ZZ)
end

But then it proceeds to this, which throws an exception because c.value is not defined:

            Core.eval(sandbox, Expr(:global, Expr(:(=), :ans, QuoteNode(c.value))))

But how is that possible? Hrm

[fingolfin]

Just to explain, I know that the access to c.value is throwing the exception because I moved it to a separate line; specifically, I inserted this code before the Core.eval and after the call to `IOCapture.capture:

            println("IOCapture.capture complete")
            println("typeof(c) = $(typeof(c))")
            println("c = $c")
            println("c.value = $(c.value)")

and got this output:

IOCapture.capture complete
typeof(c) = NamedTuple{(:value, :output, :error, :backtrace), Tuple{AbstractAlgebra.Generic.IdentityMap{AbstractAlgebra.Integers{BigInt}}, String, Bool, Vector{Ptr{Nothing}}}}
┌ Error: Doctesting failed
│   exception =
│    UndefRefError: access to undefined reference
│    Stacktrace:
│      [1] show(io::IOBuffer, t::NamedTuple{(:value, :output, :error, :backtrace), Tuple{AbstractAlgebra.Generic.IdentityMap{AbstractAlgebra.Integers{BigInt}}, String, Bool, Vector{Ptr{Nothing}}}})
│        @ Base ./namedtuple.jl:164
...

Very, very strange. I'll try and see if I can use something more advanced like Infiltrator to learn more.

[thofma]

(P.S. I found it a bit faster with JULIA_DEBUG=Documenter) but I don't understand how a named tuple can have undefined references.

[fingolfin]

Infilitrator didn't really help because it could not enter after c was created (I guess that's because it looks at all local variables and touching c in any way blows up).

The type for the NamedTuple also explicitly says that the value component has type AbstractAlgebra.Generic.IdentityMap{AbstractAlgebra.Integers{BigInt}}. So there shouldn't be a way for it to be undefined? But still a UndefRefError is thrown, by getfield... Indeed:

            println("IOCapture.capture complete")
            println("typeof(c) = $(typeof(c))")
            println("nfields(c) = $(nfields(c))")
            println("fieldtype(c,1) = $(fieldtype(typeof(c), 1))")
            println("getfield(c,1) = $(getfield(c, 1))")
            println("c = $c")
            println("c.value = $(c.value)")

results in this output:

IOCapture.capture complete
typeof(c) = NamedTuple{(:value, :output, :error, :backtrace), Tuple{AbstractAlgebra.Generic.IdentityMap{AbstractAlgebra.Integers{BigInt}}, String, Bool, Vector{Ptr{Nothing}}}}
nfields(c) = 4
fieldtype(c,1) = AbstractAlgebra.Generic.IdentityMap{AbstractAlgebra.Integers{BigInt}}
┌ Error: Doctesting failed
│   exception =
│    UndefRefError: access to undefined reference
...

[fingolfin]

I could not yet figure out what causes the weirdness we saw before, but @thofma found a workaround: instead of ZZ, we use a polynomial ring, then it works.. No idea why, but let's move on for now.