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

Erroneous Errors with `checkdocs`

Open pulsipher opened this issue 1 year ago • 0 comments

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.

pulsipher avatar Jul 03 '24 18:07 pulsipher