Documentation: API luals Annotations And Help

[alex-courtis]

api.lua exposes implementation details and does not contain all parameter and return types, notably nvim_tree.api.Node, which is currently defined in _meta/api.lua

Refactor api.lua to be an empty-function interface similar to /usr/share/nvim/runtime/lua/vim/lsp/diagnostic.lua and /usr/share/nvim/runtime/lua/vim/lsp/_meta/protocol.lua. /usr/share/nvim/runtime/lua/vim/_meta/api.lua is desirable, however that assumes that vim.api exists as a global i.e. not required.

See Api.decorator.UserDecorator for desired API shape.

A mechanism to hydrate the api with implementations must be built, so that the user may require it. There doesn't appear to be good prior art in other plugins; they link to implementations or stubs that confuse LSP.

See #2668

[alex-courtis]

Classes should also be exposed e.g. nvim_tree.api.DirectoryNode so that users may test type. See #3090 (reply in thread)

[alex-courtis]

Follows #2934