oscar-system / Oscar.jl

A comprehensive open source computer algebra system for computations in algebra, geometry, and number theory.
https://www.oscar-system.org
Other
366 stars 129 forks source link

a problem with the Julia help system #1314

Open ThomasBreuer opened 2 years ago

ThomasBreuer commented 2 years ago

Currently I find the following docstring for gen in the Oscar dev documentation of the abelian closure of the rationals.

gen(M::SubQuo{T}, i::Int) where T

Return the ith generator of M.

This docstring comes from the file src/Modules/UngradedModules.jl. The line that causes its inclusion is

gen(::QabField)

(see docs/src/NumberTheory/abelian_closure.md). Apparently the intended docstring from src/Rings/AbelianClosure.jl belongs to

gen(K::QabField{AnticNumberField})

Thus it is clear how to fix the problem.

Apparently we do not get an error message when building the documentation because the abovementioned docstring is found, but why is it found? In a Julia session, I get the following.

julia> using Oscar
[...]

help?> gen(::QabField)
  gen(M::SubQuo{T}, i::Int) where T

  Return the ith generator of M.

help?> gen(::QabField{AnticNumberField})
  gen(K::QabField)

  Return the generator of the abelian closure K that can be used to construct
  primitive roots of unity.

  ────────────────────────────────────────────────────────────────────────────

  gen(M::SubQuo{T}, i::Int) where T

  Return the ith generator of M.

Thus I get the wrong docstring also when the correct signature is entered. Why? (This docstring is the last one that is shown when one enters ?gen, but this should not matter.)

thofma commented 2 years ago

Help mode lookup and Documenter signature lookup are unrelated.

I am sure it is either https://github.com/JuliaLang/julia/issues/20064, https://github.com/JuliaDocs/Documenter.jl/issues/839 or https://github.com/JuliaLang/julia/issues/29437 :)

ThomasBreuer commented 2 years ago

@thofma Thanks.

Help mode lookup and Documenter signature lookup are unrelated.

Part of the discussion in JuliaDocs/Documenter.jl/issues/839 expresses this. However, then we have (at least) two bugs here, one in the help system and one in Documenter, since the unrelated docstring is fetched in both situations.