Fix 'docstrings potentially missing' warnings

[schillic]

Creating the documentation warns about potentially missing docstrings.
However, they are defined and occur properly in the final documentation.

Most notably:

• LazySets.σ
• LazySets.apply_recipe

For the non-apply_recipe functions the problem is related to type parameters.

[schillic]

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.

[schillic]

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, ... ])

[schillic]

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}

[schillic]

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.

[schillic]

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...

[mforets]

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

[schillic]

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

[mforets]

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

[schillic]

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

[schillic]

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

[schillic]

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