ci: lint comment annotations

Makefile

@@ -91,13 +91,20 @@ $(STYLUA_ZIP):
 stylua: $(STYLUA_ZIP)
 	unzip $<
 
+LUA_FILES := \
+    lua/**/*.lua \
+    lua/*.lua \
+    test/*_spec.lua
+
 .PHONY: stylua-check
 stylua-check: stylua
-	./stylua --check lua/**/*.lua
+	./stylua --check $(LUA_FILES)
+	@! grep -n -- '---.*nil' $(LUA_FILES) \
+		|| (echo "Error: Found 'nil' in annotation, please use '?'" && exit 1)
+	@! grep -n -- '---@' $(LUA_FILES) \
+		|| (echo "Error: Found '---@' in Lua files, please use '--- @'" && exit 1)
 
 .PHONY: stylua-run
 stylua-run: stylua
-	./stylua \
-		lua/**/*.lua \
-		lua/*.lua \
-		test/*_spec.lua
+	./stylua $(LUA_FILES)
+	sed -i -r 's/---@/--- @/g' $(LUA_FILES)

lua/treesitter-context.lua

@@ -85,8 +85,9 @@ local function close_all()
   end
 end
 
----@param bufnr integer
----@param winid integer
+--- @param bufnr integer
+---
+--- @param winid integer
 local function cannot_open(bufnr, winid)
   return not attached[bufnr]
     or vim.bo[bufnr].filetype == ''
@@ -95,7 +96,7 @@ local function cannot_open(bufnr, winid)
     or api.nvim_win_get_height(winid) < config.min_window_height
 end
 
----@param winid integer
+--- @param winid integer
 local update_single_context = throttle_by_id(function(winid)
   -- Remove leaked contexts firstly.
   local current_win = api.nvim_get_current_win()
@@ -131,7 +132,7 @@ local update_single_context = throttle_by_id(function(winid)
   require('treesitter-context.render').open(bufnr, winid, context_ranges, context_lines)
 end)
 
----@param args table
+--- @param args table
 local function update(args)
   if args.event == 'OptionSet' and args.match ~= 'number' and args.match ~= 'relativenumber' then
     return
@@ -156,9 +157,9 @@ local M = {
 
 local group = augroup('treesitter_context_update', {})
 
----@param event string|string[]
----@param callback fun(args: table)
----@param opts? vim.api.keyset.create_autocmd
+--- @param event string|string[]
+--- @param callback fun(args: table)
+--- @param opts? vim.api.keyset.create_autocmd
 local function autocmd(event, callback, opts)
   opts = opts or {}
   opts.callback = callback
@@ -270,7 +271,7 @@ end
 
 local did_init = false
 
----@param options? TSContext.UserConfig
+--- @param options? TSContext.UserConfig
 function M.setup(options)
   -- NB: setup  may be called several times.
   if options then
@@ -289,7 +290,7 @@ function M.setup(options)
   end
 end
 
----@param depth integer? default 1
+--- @param depth integer? default 1
 function M.go_to_context(depth)
   depth = depth or 1
   local line = api.nvim_win_get_cursor(0)[1]

lua/treesitter-context/cache.lua

@@ -1,17 +1,17 @@
 local M = {}
 
 ---Memoize a function using hash_fn to hash the arguments.
----@generic F: function
----@param fn F
----@param hash_fn fun(...): any
----@return F
+--- @generic F: function
+--- @param fn F
+--- @param hash_fn fun(...): any
+--- @return F
 function M.memoize(fn, hash_fn)
-  local cache = setmetatable({}, { __mode = 'kv' }) ---@type table<any,any>
+  local cache = setmetatable({}, { __mode = 'kv' }) --- @type table<any,any>
 
   return function(...)
     local key = hash_fn(...)
     if cache[key] == nil then
-      local v = fn(...) ---@type any
+      local v = fn(...) --- @type any
       cache[key] = v ~= nil and v or vim.NIL
     end
 

lua/treesitter-context/context.lua

@@ -67,9 +67,9 @@ local function calc_max_lines(winid)
   return max_lines
 end
 
----@param node TSNode
----@param bufnr integer
----@return string
+--- @param node TSNode
+--- @param bufnr integer
+--- @return string
 local function hash_args(node, bufnr)
   return table.concat({
     node:id(),
@@ -126,8 +126,8 @@ local context_range = cache.memoize(function(node, bufnr, query)
   end
 end, hash_args)
 
----@param lang string
----@return vim.treesitter.Query?
+--- @param lang string
+--- @return vim.treesitter.Query?
 local function get_context_query(lang)
   local ok, query = pcall(get_query, lang, 'context')
 
@@ -143,10 +143,10 @@ local function get_context_query(lang)
   return query
 end
 
----@param context_ranges Range4[]
----@param context_lines string[][]
----@param trim integer
----@param top boolean
+--- @param context_ranges Range4[]
+--- @param context_lines string[][]
+--- @param trim integer
+--- @param top boolean
 local function trim_contexts(context_ranges, context_lines, trim, top)
   while trim > 0 do
     local idx = top and 1 or #context_ranges
@@ -203,9 +203,9 @@ end
 
 local M = {}
 
----@param bufnr integer
----@param range Range4
----@return vim.treesitter.LanguageTree[]
+--- @param bufnr integer
+--- @param range Range4
+--- @return vim.treesitter.LanguageTree[]
 local function get_parent_langtrees(bufnr, range)
   local root_tree = vim.treesitter.get_parser(bufnr)
   if not root_tree then
@@ -259,10 +259,10 @@ end
 --- Creates a copy of a list-like table such that any nested tables are
 --- "unrolled" and appended to the result.
 ---
----@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
+--- @see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
----@param t table List-like table
----@return table Flattened copy of the given list-like table
+--- @param t table List-like table
+--- @return table Flattened copy of the given list-like table
 local function tbl_flatten(t)
   local result = {}
   --- @param _t table<any,any>

lua/treesitter-context/render.lua

@@ -7,7 +7,7 @@ local config = require('treesitter-context.config')
 local ns = api.nvim_create_namespace('nvim-treesitter-context')
 
 --- List of free buffers that can be reused.
----@type integer[]
+--- @type integer[]
 local buffer_pool = {}
 
 local MAX_BUFFER_POOL_SIZE = 20
@@ -98,9 +98,9 @@ local function get_gutter_width(winid)
   return fn.getwininfo(winid)[1].textoff
 end
 
----@param name string
----@param from_buf integer
----@param to_buf integer
+--- @param name string
+--- @param from_buf integer
+--- @param to_buf integer
 local function copy_option(name, from_buf, to_buf)
   --- @cast name any
   local current = vim.bo[from_buf][name]
@@ -110,11 +110,11 @@ local function copy_option(name, from_buf, to_buf)
   end
 end
 
----@param bufnr integer
----@param row integer
----@param col integer
----@param opts vim.api.keyset.set_extmark
----@param ns0? integer
+--- @param bufnr integer
+--- @param row integer
+--- @param col integer
+--- @param opts vim.api.keyset.set_extmark
+--- @param ns0? integer
 local function add_extmark(bufnr, row, col, opts, ns0)
   local ok, err = pcall(api.nvim_buf_set_extmark, bufnr, ns0 or ns, row, col, opts)
   if not ok then
@@ -249,9 +249,9 @@ local function build_lno_str(win, lnum, width)
   return string.format('%' .. width .. 'd', relnum or lnum)
 end
 
----@param bufnr integer
----@param row integer
----@param hl_group 'TreesitterContextBottom' | 'TreesitterContextLineNumberBottom'
+--- @param bufnr integer
+--- @param row integer
+--- @param hl_group 'TreesitterContextBottom' | 'TreesitterContextLineNumberBottom'
 local function highlight_bottom(bufnr, row, hl_group)
   add_extmark(bufnr, row, 0, {
     end_line = row + 1,
@@ -303,10 +303,10 @@ local function set_lines(bufnr, lines)
   return redraw
 end
 
----@param win integer
----@param bufnr integer
----@param contexts Range4[]
----@param gutter_width integer
+--- @param win integer
+--- @param bufnr integer
+--- @param contexts Range4[]
+--- @param gutter_width integer
 local function render_lno(win, bufnr, contexts, gutter_width)
   local lno_text = {} --- @type string[]
   local lno_highlights = {} --- @type StatusLineHighlight[][]
@@ -324,7 +324,7 @@ local function render_lno(win, bufnr, contexts, gutter_width)
   highlight_bottom(bufnr, #lno_text - 1, 'TreesitterContextLineNumberBottom')
 end
 
----@param context_winid? integer
+--- @param context_winid? integer
 local function close(context_winid)
   vim.schedule(function()
     if context_winid == nil or not api.nvim_win_is_valid(context_winid) then
@@ -356,9 +356,9 @@ local function horizontal_scroll_contexts(winid, context_winid)
   end
 end
 
----@param bufnr integer
----@param ctx_bufnr integer
----@param contexts Range4[]
+--- @param bufnr integer
+--- @param ctx_bufnr integer
+--- @param contexts Range4[]
 local function copy_extmarks(bufnr, ctx_bufnr, contexts)
   local offset = 0
   for _, context in ipairs(contexts) do

test/contexts_spec.lua

@@ -10,8 +10,8 @@ local tc_helpers = require('test.helpers')
 local install_langs = tc_helpers.install_langs
 local get_langs = tc_helpers.get_langs
 
----@param line string
----@return string?
+--- @param line string
+--- @return string?
 local function parse_directive(line)
   --- @type string?
   local directive = line:match('{{([A-Z]+)}}')