phaazon
EmmyLua annotations for external-facing APIs
I'm working again on integrating your wonderful plugin with lean.nvim for custom support for our infoview feature. I wanted to ask what your thoughts are on EmmyLua annotations for better autocompletion/hover support via sumneko-lua when using this plugin externally. Of course, adding such annotations means that there's a bit more to maintain, so I don't think we should go overboard with it (especially for parts that are susceptible to refactor), but I think we can strike a balance by mainly having them for external-facing APIs. For example, here are some annotations corresponding to the blurb at the top of hop/jump_target.lua:
---@class HopJumpTarget @A text-position-based target that can be jumped to.
---@field line integer @0-indexed line number of this jump target.
---@field column integer @1-byte-indexed column number of this jump target.
---@field length integer @Byte length of this jump target.
---@field buffer integer @Buffer handle of this jump target.
---@field window integer @Window handle of this jump target.
---@class HopIndirectJumpTarget @A reference to a `HopJumpTarget` that can be used for indirect sorting.
---@field index integer @Jump target index to be used at this position.
---@field score integer @Numeric score used for sorting; higher scoring positions come first.
---@class HopJumpDict @A table for providing an ordered list of jump targets from which hints can be constructed.
---@field jump_targets HopJumpTarget[] @List of jump targets to hint; order can be overriden by `indirect_jump_targets`.
---@field indirect_jump_targets? HopIndirectJumpTarget[] @List of references into `jump_targets` encoding their hint order.
That’s potentially something I would like, yes, but it would require a big PR doing only this, which I’m okay to accept if anyone would like to go for it. However, I plan to deprecate and remove some stuff from the API so I’m not completely sure about what to do.
