Apply easy suggestions (part2)

lua/luasnip/extras/init.lua

@@ -122,7 +122,7 @@ return {
 	--- s("extras4", { i(1), t { "", "" }, extras.rep(1) })
 	--- ```
 	---
-	---@param node_ref LuaSnip.NodeRef a single [Node Reference](#node-reference).
+	---@param node_ref LuaSnip.NodeRef a single [Node Reference](../../../DOC.md#node-reference).
 	---@return LuaSnip.FunctionNode
 	rep = function(node_ref)
 		return F(function(args)

lua/luasnip/nodes/choiceNode.lua

@@ -123,7 +123,7 @@ function ChoiceNode:subsnip_init()
 		choice.parent = self.parent
 		-- only insertNode needs this. (?)
 		if
-			vim.list_contains(
+			util.list_contains(
 				{ types.textNode, types.insertNode, types.functionNode },
 				choice.type
 			)

lua/luasnip/nodes/node.lua

@@ -14,7 +14,7 @@ local describe = require("luasnip.util.log").describe
 ---@field key? any Key to identify the node with.
 ---@field node_ext_opts LuaSnip.NodeExtOpts
 ---@field merge_node_ext_opts boolean
----@field node_callbacks {["enter"|"leave"]: fun(node:LuaSnip.Node)}
+---@field node_callbacks {[LuaSnip.EventType]: fun(node:LuaSnip.Node)}
 
 ---@class LuaSnip.Node: LuaSnip.NormalizedNodeOpts
 ---@field pos? integer Jump-index of the node
@@ -254,21 +254,16 @@ end
 
 ---@param event LuaSnip.EventType
 function Node:event(event)
-	-- FIXME(@bew): wrong type for node_callbacks ?
-	-- We index witha EventType(integer), but the field definition uses string
-	-- keys "enter"/"leave" 🤔
 	local node_callback = self.node_callbacks[event]
 	if node_callback then
 		node_callback(self)
 	end
 
 	-- try to get the callback from the parent.
 	if self.pos then
-		-- node needs position to get callback (nodes may not have position if
-		-- defined in a choiceNode, ie. c(1, {
-		--	i(nil, {"works!"})
-		-- }))
-		-- works just fine.
+		-- The node needs position to get callback
+		-- (nodes may not have position if defined in a choiceNode)
+		-- ie. `c(1, { i(nil, {"works!"}) }))` works just fine.
 		local parent_callback = self.parent.callbacks[self.pos][event]
 		if parent_callback then
 			parent_callback(self)

lua/luasnip/nodes/snippet.lua

@@ -60,16 +60,6 @@ local callbacks_mt = {
 -- declare SN here, is needed in metatable.
 local SN
 
-local stored_mt = {
-	__index = function(table, key)
-		-- default-node is just empty text.
-		local val = SN(nil, { iNode.I(1) })
-		val.is_default = true
-		rawset(table, key, val)
-		return val
-	end,
-}
-
 ---@class LuaSnip.BareInternalSnippet: LuaSnip.Node
 ---  To be used as a base for all snippet-like nodes (Snippet, SnippetProxy, ..)
 ---
@@ -238,6 +228,16 @@ local function init_snippetNode_opts(opts)
 	return in_node
 end
 
+local stored_mt = {
+	__index = function(table, key)
+		-- default-node is just empty text.
+		local val = SN(nil, { iNode.I(1) })
+		val.is_default = true
+		rawset(table, key, val)
+		return val
+	end,
+}
+
 ---@param opts LuaSnip.Opts.Snippet
 ---@return LuaSnip.NormalizedSnippetOpts
 local function init_snippet_opts(opts)
@@ -628,7 +628,7 @@ end
 ---  This overrides the filetype the snippet is added (via `add_snippet`) as.
 
 ---@class LuaSnip.Opts.Snippet: LuaSnip.Opts.SnippetNode
----@field stored? {[string]: LuaSnip.Node}
+---@field stored? {[string]: LuaSnip.Node} Snippet-level state for restore node.
 
 ---@param context string|LuaSnip.SnipContext The snippet context.
 ---  Passing a string is equivalent to passing `{ trig = <the string> }`.

lua/luasnip/util/events.lua

@@ -9,6 +9,9 @@ local EventType = {
 }
 
 local M = setmetatable({}, { __index = EventType })
+-- NOTE: The metatable is set so that callers of this `events` module can do
+-- `events.change_choice` to get a named value from the enum, while leaving the
+-- enum definition standalone to avoid adding unnecessary enum fields.
 
 ---@param node_type LuaSnip.NodeType
 ---@param event_id LuaSnip.EventType

lua/luasnip/util/types.lua

@@ -12,6 +12,9 @@ local NodeType = {
 }
 
 local M = setmetatable({}, { __index = NodeType })
+-- NOTE: The metatable is set so that callers of this `types` module can do
+-- `types.insertNode` to get a named value from the enum, while leaving the
+-- enum definition standalone to avoid adding unnecessary enum fields.
 
 local refs = {
 	{ value = NodeType.textNode, name = "textNode", pascal_name = "TextNode" },

lua/luasnip/util/util.lua

@@ -479,6 +479,21 @@ local function copy3(obj, seen)
 	return setmetatable(res, getmetatable(obj))
 end
 
+--- Checks if a list-like table (integer keys without gaps) contains `needle`.
+---@param t table Table to check (must be list-like, not validated)
+---@param needle any Value to compare
+---@return boolean _ `true` if `t` contains `needle`
+local function list_contains(t, needle)
+  vim.validate('t', t, 'table')
+
+  for _, v in ipairs(t) do
+    if v == needle then
+      return true
+    end
+  end
+  return false
+end
+
 return {
 	get_cursor_0ind = get_cursor_0ind,
 	set_cursor_0ind = set_cursor_0ind,
@@ -525,4 +540,5 @@ return {
 	pos_from_offset = pos_from_offset,
 	shallow_copy = shallow_copy,
 	copy3 = copy3,
+	list_contains = list_contains,
 }