Documenter.jl
Documenter.jl copied to clipboard
Bug in missing docs detection
Consider the following reduced example:
module Tmp
export f
"method for Real"
function f(::Vector{<:Real}) end
"method for String"
function f(::Vector{<:AbstractString}) end
end # module
and a docs page
```@meta
CurrentModule=Tmp
```
```@docs
f(::Vector{<:Real})
f(::Vector{<:AbstractString})
```
when I run
Documenter.makedocs(sitename="Tmp", modules=[Tmp])
I sometimes get missing docs errors:
julia> include("docs/make.jl")
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
┌ Warning: 2 docstrings not included in the manual:
│
│ Tmp.f :: Tuple{Vector{<:Real}}
│ Tmp.f :: Tuple{Vector{<:AbstractString}}
│
│ These are docstrings in the checked modules (configured with the modules keyword)
│ that are not included in @docs or @autodocs blocks.
└ @ Documenter.DocChecks .../Documenter/src/Utilities/Utilities.jl:34
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
Sometimes both docstrings are marked as missing, sometimes it's only 1, and sometimes there is no error at all. I get different behaviors by restarting Julia entirely, but within the same REPL session the behavior seems to be consistent.
However, both methods are always in the actual generated docs page, it is only the missing docs check that is wrong.
I tried adding some instrumentation here, which showed the following:
object = Documenter.Utilities.Object(Tmp.f, Tuple{Vector{<:Real}})
binding = Tmp.f
signatures = Set(Type[Tuple{Vector{<:Real}}, Tuple{Vector{<:AbstractString}}])
object.signature = Tuple{Vector{<:Real}}
object.signature in signatures = false
object = Documenter.Utilities.Object(Tmp.f, Tuple{Vector{<:AbstractString}})
binding = Tmp.f
signatures = Set(Type[Tuple{Vector{<:Real}}, Tuple{Vector{<:AbstractString}}])
object.signature = Tuple{Vector{<:AbstractString}}
object.signature in signatures = false
So it seems like the check here is not being hit. However, running the same check manually in the repo works fine:
julia> signatures = Set(Type[Tuple{Vector{<:Real}}, Tuple{Vector{<:AbstractString}}])
Set{Type} with 2 elements:
Tuple{Vector{<:AbstractString}}
Tuple{Vector{<:Real}}
julia> signature = Tuple{Vector{<:AbstractString}}
Tuple{Vector{<:AbstractString}}
julia> signature in signatures
true
so I'm not really sure what's going on