Docstring for empty function prevents method docstrings from appearing

[mhauru]

MWE: make.jl:

module Dada

export f

"""
docstring for f with no methods
"""
function f end

"""
docstring for f(::Int)

You won't see me!
"""
f(::Int) = 1

end

using Documenter, .Dada

makedocs(sitename="Dada")

src/index.md:

```@docs
f
```

After running julia make.jl, the output build/index.html has

Main.Dada.f — Function

docstring for f with no methods

In other words, the docstring for f(::Int) isn't included in @docs f if there's also a docstring for an empty, methodless f. You can get it with @docs f(::Int). Note that REPL help?> f still shows both.

I didn't find anything about this in the documentation, so I assume it's a bug. The behavior also doesn't make sense to me.

[mortenpi]

This is related to #839.

It's a bit of a double edged sword: there might be cases where you just want to include the generic definition attached to the function, but not the ones for specific methods (e.g. you want to document the specific methods together with the types on another page).

Just for the record, the way to get both is to do

```@docs
f
f(::Int)
```

[mhauru]

I guess the issue here is that @docs f is the natural syntax for both "all methods of f" and for "the generic, no-method f". I do find it non-optimal that the meaning changes based on whether there's a generic docstring defined or not. However, I can also see the need for having some syntax for getting the generic docstring only, and I don't know what else it would be, other than @docs f.

Regardless, I think it would be good to have this documented.

[mortenpi]

I guess the issue here is that @docs f is the natural syntax for both "all methods of f" and for "the generic, no-method f".

Exactly. And I agree that it's non-optimal to have the behavior change. However, I think I then lean towards having @docs f include just the generic docstring, if available, and throw a missing docstring error otherwise. To get the current behavior, we'd have to introduce some new syntax.

[mhauru]

I certainly see the sense in which that is the most natural solution, but it is a heavily breaking one. How much that should weigh in the decision is not for me to say though, I'm just a lowly user. :)

[matthias314]

Whatever option is chosen, it would be great if the documentation talked about it.

Moreover, in the MWE above the docstring for f(::Int) is silently discarded at present. In other cases Documenter.jl gives an error if some docstring is not included into the documentation.