Documenter.jl icon indicating copy to clipboard operation
Documenter.jl copied to clipboard

Bug in missing docs detection

Open JackDunnNZ opened this issue 2 years ago • 0 comments

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

JackDunnNZ avatar Jul 20 '22 04:07 JackDunnNZ