Overloading @usage doesn't work properly

[dbarnett]

The documentation says vimdoc supports multiple @usage directives on the same command or function. This does work for very simple cases, but has quite a few bugs.

Attempting to link to such a function or command triggers errors like "Found multiple FUNCTIONs named Foo".

Each usage is independently checked against the signature and warns if any isn't an exact match for the signature. For instance, the following is perfectly correct, but vimdoc complains about it:

""
" @usage {x}
" @usage {x} {y}
function! foo#Bar(x, ...) abort

An empty @usage directive creates a new separate usage, contrary to what the documentation says. This feature would actually be problematic/surprising in some cases where there actually is a no-arg usage, so if we really do implement it we should consider a more explicit syntax or make sure you can still have an empty @usage directive if it comes before others or something.

[dbarnett]

These may be non-trivial to fix because they all stem from the fact that vimdoc's model is currently too simplistic: it creates multiple independent blocks and has no concept of the fact that they relate to the same code object.

Also, checking the actual function signature against multiple usage declarations could require some clever logic. The usage declaration should still be required to be consistent and complete. For example, this case should complain about an inconsistent usage since there is no actual zero-arg variant:

""
" @usage [x]
function! foo#Bar(x, ...)

while this case should complain about incomplete usage since the single-arg variant isn't documented:

""
" @usage {x} {y}
" @usage {x} {y} {z}
function! foo#Bar(x, ...)