there is something that has been bugging me since I started writing plugins in Lua: how do you mark up the “module” part of a symbol. This is not a problem with the built-in modules like
vim.lsp because they are always in the global environment, but it is a problem with modules that need to be
Lua does not really have a module system, but it does a good job of pretending that it does. Suppose I have a plugin
foo.nvim that contains a file
lua/foo.lua which returns a table. I can then reference the symbol
require('foo').bar. Simple enough.
But how do I document this? Popular plugins like Telescope would document it as
foo.bar, but this is technically wrong because there is no global
foo symbol. This becomes a real problem in Telescope with a tag like
telescope.builtin.lsp_definitions(). How do I get that symbol? Is it
require('telescope.builtin.lsp_defintions')? It’s the second one. I have to scroll all the way up to the beginning of the section to find the answer in prose.
Here is my proposal: write the module name in quotes.
In Lua strings cannot have fields, do there is no danger of confusion. The only problem I can foresee is that in Vim options are tagged with quotes (e.g.
'syntax'), but they don’t have any fields either.
What is your opinion? Alternatives? And how do we communicate it to plugin authors? I would have written it in
help-writing but it doesn’t look anyone reads that section.