Repository navigation
Overloading @usage doesn't work properly #38
Description
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, ...) abortAn 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.
Activity
dbarnett commentedon Apr 1, 2014
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:
while this case should complain about incomplete usage since the single-arg variant isn't documented:
vinsymoyya commentedon Nov 12, 2026
Opened #147 for the link-resolution failure described here. Secondary usage blocks intentionally have no tag; lookup now uses the primary definition instead of treating those variants as duplicate definitions. Genuinely duplicate definitions still raise an error.
Function and command link regressions fail on current upstream and pass with the fix; the full local test/doctest run passes all 12 tests. This patch addresses the link-generation crash; the separate signature-validation discussion remains outside its scope.