chore: add some more type annotations

Author: wincent

lua/wincent/commandt/private/buffer_visible.lua

@@ -1,14 +1,15 @@
 -- SPDX-FileCopyrightText: Copyright 2022-present Greg Hurrell and contributors.
 -- SPDX-License-Identifier: BSD-2-Clause
 
-local buffer_visible = nil
-
--- `vim.fn.bufwinnr()` doesn't see windows in other tabs, meaning we open them
--- again instead of switching to the other tab; but `vim.fn.bufname()` sees
--- hidden buffers, and if we try to open one of those, we get an unwanted split.
--- So, this function does some additional work to check whether `buffer` is
--- _really_ visible.
-buffer_visible = function(buffer)
+--- `vim.fn.bufwinnr()` doesn't see windows in other tabs, meaning we open them
+--- again instead of switching to the other tab; but `vim.fn.bufname()` sees
+--- hidden buffers, and if we try to open one of those, we get an unwanted
+--- split. So, this function does some additional work to check whether `buffer`
+--- is _really_ visible.
+---
+--- @param buffer string|number
+--- @return boolean
+local function buffer_visible(buffer)
   -- TODO: port this to use lower-level nvim APIs, if there are any that could
   -- be used here...
   if vim.fn.bufwinnr('^' .. buffer .. '$') ~= -1 then

lua/wincent/commandt/private/concat.lua

@@ -1,11 +1,12 @@
 -- SPDX-FileCopyrightText: Copyright 2022-present Greg Hurrell and contributors.
 -- SPDX-License-Identifier: BSD-2-Clause
 
-local concat = nil
-
--- Utility function that concatenates one or more list-like tables into a new
--- list.
-concat = function(...)
+--- Utility function that concatenates one or more list-like tables into a new
+--- list.
+---
+--- @param ... any[]
+--- @return any[]
+local function concat(...)
   local final = {}
   for _, t in ipairs({ ... }) do
     for _, v in ipairs(t) do

lua/wincent/commandt/private/includes.lua

@@ -1,6 +1,11 @@
 -- SPDX-FileCopyrightText: Copyright 2025-present Greg Hurrell and contributors.
 -- SPDX-License-Identifier: BSD-2-Clause
 
+--- Returns `true` if `value` exists in list-like table, `t`.
+---
+--- @param t any[]
+--- @param value any
+--- @return boolean
 local function includes(t, value)
   for _, candidate in ipairs(t) do
     if candidate == value then

lua/wincent/commandt/private/is_integer.lua

@@ -1,7 +1,11 @@
 -- SPDX-FileCopyrightText: Copyright 2022-present Greg Hurrell and contributors.
 -- SPDX-License-Identifier: BSD-2-Clause
 
-local is_integer = function(numberish)
+--- Returns `true` if `numberish` is an integer.
+---
+--- @param numberish any
+--- @return boolean
+local function is_integer(numberish)
   return type(numberish) == 'number' and math.floor(numberish) == numberish
 end
 

lua/wincent/commandt/private/is_list.lua

@@ -1,7 +1,11 @@
 -- SPDX-FileCopyrightText: Copyright 2022-present Greg Hurrell and contributors.
 -- SPDX-License-Identifier: BSD-2-Clause
 
-local is_list = function(value)
+--- Returns `true` if `value` is a list-like table.
+---
+--- @param value any
+--- @return boolean
+local function is_list(value)
   if type(value) ~= 'table' then
     return false
   elseif #value > 0 then

lua/wincent/commandt/private/is_table.lua

@@ -3,7 +3,11 @@
 
 local is_list = require('wincent.commandt.private.is_list')
 
-local is_table = function(value)
+--- Returns `true` if `value` is a dictionary-like table (not a list).
+---
+--- @param value any
+--- @return boolean
+local function is_table(value)
   return type(value) == 'table' and (#value == 0 or not is_list(value))
 end
 

lua/wincent/commandt/private/keys.lua

@@ -1,10 +1,11 @@
 -- SPDX-FileCopyrightText: Copyright 2022-present Greg Hurrell and contributors.
 -- SPDX-License-Identifier: BSD-2-Clause
 
-local keys = nil
-
--- Utility function that returns a list of keys in the given table.
-keys = function(t)
+--- Utility function that returns a list of keys in the given table, `t`.
+---
+--- @param t table
+--- @return any[]
+local function keys(t)
   local final = {}
   for k, _ in pairs(t) do
     table.insert(final, k)

lua/wincent/commandt/private/len.lua

@@ -1,50 +1,55 @@
 -- SPDX-FileCopyrightText: Copyright 2025-present Greg Hurrell and contributors.
 -- SPDX-License-Identifier: BSD-2-Clause
 
--- Temporary wrapper to give us compatibility between Neovim v0.10.4 and
--- more recent nightlies; see: https://github.com/wincent/command-t/issues/434
---
--- `:help str_utfindex` in v0.10.4:
---
---     vim.str_utfindex({str}, {index})                          *vim.str_utfindex()*
---         Convert byte index to UTF-32 and UTF-16 indices. If {index} is not
---         supplied, the length of the string is used. All indices are zero-based.
---
---         Embedded NUL bytes are treated as terminating the string. Invalid UTF-8
---         bytes, and embedded surrogates are counted as one code point each. An
---         {index} in the middle of a UTF-8 sequence is rounded upwards to the end of
---         that sequence.
---
---         Parameters: ~
---           • {str}    (`string`)
---           • {index}  (`integer?`)
---
---         Return (multiple): ~
---             (`integer`) UTF-32 index
---             (`integer`) UTF-16 index
---
---
--- `:help str_utfindex` in nightly:
---
---                                                               *vim.str_utfindex()*
---     vim.str_utfindex({s}, {encoding}, {index}, {strict_indexing})
---         Convert byte index to UTF-32, UTF-16 or UTF-8 indices. If {index} is not
---         supplied, the length of the string is used. All indices are zero-based.
---
---         If {strict_indexing} is false then an out of range index will return
---         string length instead of throwing an error. Invalid UTF-8 bytes, and
---         embedded surrogates are counted as one code point each. An {index} in the
---         middle of a UTF-8 sequence is rounded upwards to the end of that sequence.
---
---         Parameters: ~
---           • {s}                (`string`)
---           • {encoding}         (`"utf-8"|"utf-16"|"utf-32"`)
---           • {index}            (`integer?`)
---           • {strict_indexing}  (`boolean?`) default: true
---
---         Return: ~
---             (`integer`)
-
+--- Temporary wrapper to give us compatibility between Neovim v0.10.4 and
+--- more recent nightlies; see: https://github.com/wincent/command-t/issues/434
+---
+--- `:help str_utfindex` in v0.10.4:
+---
+---     vim.str_utfindex({str}, {index})                          *vim.str_utfindex()*
+---         Convert byte index to UTF-32 and UTF-16 indices. If {index} is not
+---         supplied, the length of the string is used. All indices are zero-based.
+---
+---         Embedded NUL bytes are treated as terminating the string. Invalid UTF-8
+---         bytes, and embedded surrogates are counted as one code point each. An
+---         {index} in the middle of a UTF-8 sequence is rounded upwards to the end of
+---         that sequence.
+---
+---         Parameters: ~
+---           • {str}    (`string`)
+---           • {index}  (`integer?`)
+---
+---         Return (multiple): ~
+---             (`integer`) UTF-32 index
+---             (`integer`) UTF-16 index
+---
+---
+--- `:help str_utfindex` in nightly:
+---
+---                                                               *vim.str_utfindex()*
+---     vim.str_utfindex({s}, {encoding}, {index}, {strict_indexing})
+---         Convert byte index to UTF-32, UTF-16 or UTF-8 indices. If {index} is not
+---         supplied, the length of the string is used. All indices are zero-based.
+---
+---         If {strict_indexing} is false then an out of range index will return
+---         string length instead of throwing an error. Invalid UTF-8 bytes, and
+---         embedded surrogates are counted as one code point each. An {index} in the
+---         middle of a UTF-8 sequence is rounded upwards to the end of that sequence.
+---
+---         Parameters: ~
+---           • {s}                (`string`)
+---           • {encoding}         (`"utf-8"|"utf-16"|"utf-32"`)
+---           • {index}            (`integer?`)
+---           • {strict_indexing}  (`boolean?`) default: true
+---
+---         Return: ~
+---             (`integer`)
+---
+--- @param str string
+--- @param encoding 'utf-8' | 'utf-16' | 'utf-32'
+--- @param start_char integer?
+--- @param strict_indexing boolean?
+--- @return integer
 local function str_utfindex(str, encoding, start_char, strict_indexing)
   local success, result = pcall(function()
     -- Nightly.
@@ -58,7 +63,10 @@ local function str_utfindex(str, encoding, start_char, strict_indexing)
   return vim.str_utfindex(str, start_char)
 end
 
--- Unicode-aware `len` implementation.
+--- Unicode-aware `len` implementation.
+---
+--- @param str string
+--- @return integer
 local function len(str)
   return str_utfindex(str, 'utf-32')
 end

lua/wincent/commandt/private/merge.lua

@@ -1,29 +1,30 @@
 -- SPDX-FileCopyrightText: Copyright 2022-present Greg Hurrell and contributors.
 -- SPDX-License-Identifier: BSD-2-Clause
 
-local merge = nil
-
 local is_list = require('wincent.commandt.private.is_list')
 local is_table = require('wincent.commandt.private.is_table')
 
--- Utility function for working with functions that take optional arguments.
---
--- Creates a merged table containing items from the supplied tables, working
--- from left to right, recursively.
---
--- ie. `merge(t1, t2, t3)` will insert elements from `t1`, then `t2`, then
--- `t3` into a new table, then return the new table.
---
--- Note that:
---
--- - Values of different types will overwrite rather than merge recursively.
--- - List-like tables will overwrite rather than merge (because it is convenient
---   for user settings).
--- - Table-like tables _will_ merge recursively.
---
--- We're not depending on `vim.tbl_deep_extend()` so that we can use this
--- anywhere (eg. benchmarks, tests etc).
-merge = function(...)
+--- Utility function for working with functions that take optional arguments.
+---
+--- Creates a merged table containing items from the supplied tables, working
+--- from left to right, recursively.
+---
+--- ie. `merge(t1, t2, t3)` will insert elements from `t1`, then `t2`, then
+--- `t3` into a new table, then return the new table.
+---
+--- Note that:
+---
+--- - Values of different types will overwrite rather than merge recursively.
+--- - List-like tables will overwrite rather than merge (because it is convenient
+---   for user settings).
+--- - Table-like tables _will_ merge recursively.
+---
+--- We're not depending on `vim.tbl_deep_extend()` so that we can use this
+--- anywhere (eg. benchmarks, tests etc).
+---
+--- @param ... table? # One or more tables to merge (nil values are ignored)
+--- @return table
+local function merge(...)
   local final = {}
   for _, t in ipairs({ ... }) do
     if t ~= nil then

lua/wincent/commandt/private/str_prefix.lua

@@ -3,10 +3,14 @@
 
 local sub = require('wincent.commandt.private.sub')
 
--- Attempts to return a prefix of `str` of size `length`, as measured in screen
--- cells. If `str` if overlength, and the final character that must be trimmed
--- to bring it down to the desired length is a double-cell one, the actual
--- returned link may be off (specifically, underlength) by 1 screen cell.
+--- Attempts to return a prefix of `str` of size `length`, as measured in screen
+--- cells. If `str` if overlength, and the final character that must be trimmed
+--- to bring it down to the desired length is a double-cell one, the actual
+--- returned link may be off (specifically, underlength) by 1 screen cell.
+---
+--- @param str string
+--- @param length integer
+--- @return string
 local function str_prefix(str, length)
   if length < 1 then
     return ''