Fix 'docstrings potentially missing' warnings about lazysets.jl HOT 11 CLOSED

I had a look at the Documenter.jl code where this warning is printed.

Use case: σ for BallInf:
We have this function signature in the source code:

σ(d::AbstractVector{<:Real}, B::BallInf)

and this doc signature:

σ(::AbstractVector{Float64}, ::BallInf)

In Documenter.jl in the above-mentioned function this results in the following object:

object == LazySets.σ-Tuple{AbstractArray{Float64,1},LazySets.BallInf}
object.binding == LazySets.σ
object.signature == Tuple{AbstractArray{Float64,1},LazySets.BallInf}

So far so good. Now let us see what signature is stored in signatures:

signatures == Set(Type[ ..., Tuple{AbstractArray{#s9,1} where #s9<:Real,LazySets.BallInf}, ...])

(The identifier #s9 changes with each run.)

Documenter.jl cannot match this. So let us change the doc signature the way it seems to be expected.

σ(::AbstractVector{N} where N<:Real, ::BallInf)

This still does not help. It seems that Documenter.jl does not understand where phrases.

from lazysets.jl.

Even worse: How can we resolve the warnings for shared type parameters such as in HPolygon.jl?

addconstraint!(P::HPolygon{N}, constraint::LinearConstraint{N}) where {N<:Real}

Current docs signature:

addconstraint!(::HPolygon{Float64}, ::LinearConstraint{Float64})

The following does not work because it is not even found in an earlier phase of Documenter.jl.

addconstraint!(::HPolygon{<:Real}, ::LinearConstraint{<:Real})

Note that the expected docs signature has a strange Union type where the first entry is as expected and the second entry is just a 1-Tuple of the parametric type N:

signatures == Set(Type[ Union{Tuple{LazySets.HPolygon{N},LazySets.LinearConstraint{N}}, Tuple{N}} where N<:Real, ... ])

from lazysets.jl.

Another comment:
The reason why we do not see this warning for some other functions such as

intersection(L1::Line{N}, L2::Line{N})::Vector{N} where {N<:Real}

in LinearConstraints.jl is that Documenter.jl simply assumes the following:
If there is only one function with the given binding (i.e., function name) left, then it is the function we want.
This is also why sometimes a warning might not occur in one run and pop up in the next run again because in the first run it was the last function of its kind (depends on the iteration order of the files, which is "nondeterministic"). I saw this several times for

Base.:* :: Tuple{AbstractArray{#s13,2} where #s13<:Real,LazySets.LazySet}

from lazysets.jl.

I am now certain that this is a problem with Documenter.jl. See the following example for HPolygonOpt.jl's ∈ function:

Tuple{AbstractArray{#s1,1} where #s1<:Real,LazySets.HPolygonOpt}

This is the object that is created from the doc string. The array of signatures for this function contains the following:

Tuple{AbstractArray{#s13,1} where #s13<:Real,LazySets.HPolygonOpt}

Clearly the two tuples are identical up to renaming of the type parameter. But a == comparison returns false.

from lazysets.jl.

Another issue: The hyperlinks in the HTML documentation do not work if we include default values. See, e.g., norm for BallInf and Hyperrectangle - they point to the same entry (probably the first one, in this case BallInf).

By removing =Inf the hyperlinks are corrected, but we get more warnings...

from lazysets.jl.

i dunno.. once i tried to reproduce warnings starting from a very simple example that has say two different functions and uses where and stuff and it was ok.. so, i didn't get a minimal (non-working) example to raise an issue in Documenter.jl

from lazysets.jl.

The problem occurs as soon as you have two methods with the same name, see here.

from lazysets.jl.

then it would be nice to know if this is a known bug in documenter or not.

from lazysets.jl.

Here is a minimal example to reproduce the main problem (uses our LazySets module).
I also pushed it to this branch.

test.jl contains:

export foo

"""
This is a very nice function.
"""
function foo(::Vector{N}, ::N) where {N<:Signed}
    println("foo_signed")
end

"""
This is a very poor function.
"""
function foo(::Vector{N}, ::N) where {N<:AbstractFloat}
    println("foo_float")
end

Then in LazySets.jl include this file into the module:

include("test.jl")

Then in some docs file add (with \ removed):

\```@docs
foo(::Vector{N}, ::N) where {N<:Signed}
foo(::Vector{N}, ::N) where {N<:AbstractFloat}
\```

(Using concrete types will not help, either.)

Result:

!! XX docstrings potentially missing:
...
    LazySets.foo :: Union{Tuple{Array{N,1},N}, Tuple{N}} where N<:Signed                        
    LazySets.foo :: Union{Tuple{Array{N,1},N}, Tuple{N}} where N<:AbstractFloat
...

However, the URLs in the HTML output are created correctly:
LazySets/docs/build/lib/operations.html#LazySets.foo-Union{Tuple{Array{N,1},N},%20Tuple{N}}%20where%20N%3C:Signed

from lazysets.jl.

I have asked about this in the Documenter.jl repo.

from lazysets.jl.

This is now more or less supported. I will send a PR in the near future.

from lazysets.jl.