Hello, I don’t know where to post this, so I am starting with the more friendly place (this forum) and I will try other places if I get no answer here.
The neovim documentation is not great. At first I thought I was just not used to it, but I keep failing to extract valuable information out of it, and I end doing experiments, reading the source code or just googling what I am looking for instead. Which is a shame, because there are just little details what are missing in order to make it more usable.
I can not give general observations, because I am not that capable nor I have enough experience with the API docs, but I can give specific examples where the documentation didn’t helped me.
I will start with the most recent one, which I think applies to all API function docs. Here is the documentation for nvim__get_runtime
nvim__get_runtime({pat}, {all}, {*opts}) *nvim__get_runtime()*
Find files in runtime directories
Attributes:
{fast}
Parameters:
{pat} pattern of files to search for
{all} whether to return all matches or only the first
{options} is_lua: only search lua subdirs
Return:
list of absolute paths to the found files
By reading that, I do know what each parameter is FOR, but I don’t know what each parameter is expected to be. My intuition told me that the first one is a string, the second one a boolean and the last one a table with a single property is_lua which is supposed to be a boolean? My intuition was wrong, and I didn’t manage to make the api return anything useful. Reading the error messages I came to the conclusion that all arguments are expected to be tables? but I don’t know which format they are supposed to adhere to.
On the contrary, I had much more success with nvim_get_runtime_file, which was even better for my use case (lucky me) and from the signature my intuition was correct, however and it even contains an example, so this was a piece of cake
nvim_get_runtime_file({name}, {all}) *nvim_get_runtime_file()*
Find files in runtime directories
'name' can contain wildcards. For example
nvim_get_runtime_file("colors/*.vim", true) will return all
color scheme files. Always use forward slashes (/) in the
search pattern for subdirectories regardless of platform.
It is not an error to not find any files. An empty array is
returned then.
Attributes:
{fast}
Parameters:
{name} pattern of files to search for
{all} whether to return all matches or only the first
Return:
list of absolute paths to the found files
Why are types not specified in any of this functions?
Also, it is not clear either if the functions from vim.api namespace are preferred over those on vim.fn. If I understood the documentation correctly, vim.fn is some kind of proxy to directly access builtin VIM functions. If this is preferable to using vim.api or builtin lua functions when they are available is beyond my knowledge. Someone suggested that vim.fn is the more modern version, but after reading the docs that is no longer clear to me. For example, should I use vim.fn.extend when I want to concatenate two lua lists? Or is it better to use plain lua functions for that? Some recommendations will be very nice on that.
As always, cheers and thanks for this awesome editor