search

google / vimdoc

Helpfile generation for vim
Apache License 2.0
291 stars 29 forks source link

Deprecate @function(X) with |X()| and @command(Y) with |:Y| #47

Closed dbarnett closed 10 years ago

dbarnett commented 10 years ago

We probably don't need special directives for links to functions and commands. I don't think we realized the () and : were part of the tag when we started; since |X()| and |:Y| unambiguously link to function X and command Y, vimdoc could explicitly recognize these forms and treat them the same as it would treat @function(X) and @command(Y), making those forms unnecessary.

This has 2 advantages: It's more concise, and it's closer to the standard help format, which makes it more natural for plugin authors.

dbarnett commented 10 years ago

The only catch here is that vim occasionally uses :FOO tags when FOO isn't a literal command. For instance, :s_flags is the tag for flags accepted by :substitute, not for some "s_flags" command. Ambiguous cases are rare enough it's probably not worth worrying much over, but they might look a little weird in HTML documentation depending on how we decide to render them.

dbarnett commented 10 years ago

Another possible disadvantage to this is that it's less obvious to troubleshoot since the input matches the output for vim helpfile generation (e.g., "|foo()|" in the doc comments renders "|foo()|" into the vim helpfiles). For instance, if you accidentally type "|foo|" and leave off parentheses after the function name, it will look like it's correct and pretty much work in vim, but then generate bad HTML links (if we ever get HTML output working, #30).

I think I'm leaning towards continuing to use @function and @command. Will close this issue unless someone chimes in that they think this is really good idea.