Documenter.jl
Documenter.jl copied to clipboard
Erroneous Errors with `checkdocs`
Upon updating InfiniteOpt.jl to use checkdocs, I have found that a number docstrings are erroneously detected as not being included in the manual. All these seem to boil down to two types of functions:
First, functions with an abstracted array argument:
"""
my_func(arr::Vector{<:Real})::Int
Here is a cool docstring.
"""
my_func(arr::Vector{<:Real}) = 42
which I include my docs via a syntax like:
```@docs
my_func(::Vector{<:Real})
```
Second, functions with an optional final positional argument:
"""
my_func2(a::Int, b::Int = 1)::Int
Here is a cool docstring.
"""
my_func2(a::Int, b::Int = 1) = a + b
which I include in the docs as
```@docs
my_func2(::Int, ::Int)
```
To build the docs, I set warnonly = true and get a warning like:
┌ Warning: 2 docstrings not included in the manual:
│
│ MyPkg.my_func :: Tuple{Vector{var"#s108"} where {var"#s108"<:Real}}
│ MyPkg.myfunc2 :: Union{Tuple{Int}, Tuple{Int, Int}}
│
│ These are docstrings in the checked modules (configured with the modules keyword)
│ that are not included in canonical @docs or @autodocs blocks.
└ @ Documenter ~/.julia/packages/Documenter/qoyeC/src/utilities/utilities.jl:46
which seems to suggest that the manual is missing docstring entries for myfunc and myfunc2. However, the generated webpages do in fact include the docstrings as expected where I included them in the @docs entries.