google / google/vimdoc

Overloading @usage doesn't work properly

Open
#38 1 comment 0 reactions 0 assignees View on GitHub
bug
Dominant language
Python
Stars
306
Forks
30
PR merge metrics
No merged PRs in 30d

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:

``` VimL
""
" @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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.