`@doc` defined methods are not shown without explicitly requesting them

[tecosaur]

Hello!

I've run into a minor hiccup with the newly-developed docs for my Trash.jl package. To help with the cross-platform implementation, I have stubs with docstrings that in one file:

"""
    list() -> Vector{TrashFile}

List all entries currently in the user's trash.

See also: [`trash`](@ref), [`untrash`](@ref).
"""
function list end

@doc """
    list(trashdir::String) -> Vector{TrashFile}

List all entries currently in the trash directory `trashdir`.

See also: [`trashdir`](@ref), [`search`](@ref).
""" list(::String)

I then have @docs blocks as usual, e.g.

```@docs
Trash.list
...
```

But it seems that instead of showing all methods, only the first method is shown. I can get the second printed by adding Trash.list(::String), but other than the tedium I miss the way the docs for both methods are shown under a single function block.

I'm guessing this isn't the intended behaviour.

[mortenpi]

This is semi-intentional I'd say. The first docstring is not really attached to a method, but attached to the binding itself. So with Trash.list we're just including the docstring of the binding. It's just that if you don't have any docstring on the binding (just methods), we include all the docstrings of that binding (kind of an autodocs-y feature, really).

The practical issue of always including all docstrings of a binding is that you'll lose the fine-grained control of being able to include just the binding.

Something that I have thought about is that we could maybe introduce is some way of annotating the binding name in the at-docs block such that it behaves differently (e.g. combine binding + methods; by having something like @all Trash.list or something).