Today i learned there is 2 lua functions to assing keymaps and one is strictly better than the other

Neovim
1

so here is the thing there are 2 functions to assign keymaps from lua one is the one i found used in every tutorial i found which is vim.api.nvim_set_keymap however the api is intedend to be used for every language, so you can’t assign lua functions to that one however there is vim.keymap.set which is equal to that one but can have lua functions assigned so you don’t have to write “:lua func()” boilerplate in your config hope this helps someone.

4 Likes
2

Yeah, deciding which functions of the LUA api to use is confusing and a hard task. I guess the problem lies in the fact that most of the ones writting the docs are already very familiar with the API, so they don’t feel the urge of documenting which methods to prefer, or which ones should be used. The discoverability of the help is quite terrible IMO

3

First, it is important to distinguish between

  1. the Neovim API (nvim_foo), which is
  • versioned
  • covered by a strict contract (:h api-contract)
  • exposed in a consistent way to different endpoints (Vimscript, Lua via vim.api, RPC for remote plugins and GUIs)
  • implemented in C, usually as a direct access to Vim internals

and

  1. the Lua API (vim.foo, where foo!=api), which can
  • move faster since it is implemented in Lua
  • is allowed to break at any time (if the reason is good enough)
  • include fresh interfaces that abstract from decades of legacy Vim baggage.

The last point is exactly what’s going on here: nvim_set_keymap is a Neovim API for setting Vim mappings (and hence follows the classical Vim model very closely). This was felt to be cumbersome enough to especially new users (who wants to learn about noremap if they can avoid it?) to warrant creating a more convenient Lua API vim.keymap.set on top of it.

For most other Neovim APIs (such as creating user or autocommands), this was not the case, so there is no dedicated Lua API for them beyond accessing the Neovim API. (Because we very much try to avoid adding new and in particular competing APIs, for the very reason you mention.)

Second, if you have specific suggestions how the documentation can be improved, please open an issue (or even a PR!) about it. We of course care a lot about good and accessible documentation, but simply complaining on a forum that the “discoverability of the help is quite terrible” is not actionable and will not change anything.

2 Likes
4

Hey @clason thank you very much for the detailed explanation about the differences between the two APIs and the historical decisions around them, really helps to gain understanding on which one prefer. Up until now I thought that vim.api.nvim_foo whas the new and preferred API while vim.foo was old, what a misunderstanding!
Where did you get that information from? This is the kind of useful stuff I never find in neovim “official” page, and that is generally my main complain.
When I search about neovim things, sadly shadowed by vim all over the internet, the Neovim official docs is never within the first results, and that is problem for me because I never know how much I can trust the source I’m reading. But even if you navigate to the Neovim docs site manually to search for things, the experience is not good either. First, the site has no search capability (that I know of) so you have to manually navigate it or land into each page from the outside. I understand that it tries to take advantage of re-using the existing neovim documentation, and I understand it to save manpower and focus on better things, but IMO it should take better advantage of web technologies and not only allow search, but also offer a better viewing experience. There is no much advantage of using it outside of neovim. The same discoverability problem happens within vim, there is no search functionality there either. Yes, you will get autocomplete for :h command, but that will only give you topics, so unless you already know what you are looking for, you are out of luck discovering something you may need. I think each topic should be searchable by content AND by keywords, so you can have a more human friendly way of discovering help content.

Neovim is a fantastic and big project, and in general I prefer to not open new issues because they add noise and take time out of the maintainers, and I honestly don’t think they align with my way of thinking about documentation at all, so in general I don’t bother and as a bonus I don’t bother them :smile:

If I have to summarize, the problem I have around neovim documentation should be solved, in general, with meta-documentation things: better ways to search, more context, more human friendly messages like the one you just wrote, but specially, the most important thing, more examples. Understanding abstract concepts is hard, and having a set of good examples really reduces that mental burden.

If you think I should share this ideas in the form of a issue, just let me know and I will be more than happy to open one.