chore: cleanup docstrings

lua/neotest-golang/init.lua

@@ -11,30 +11,30 @@ local utils = require("neotest-golang.utils")
 
 local M = {}
 
----See neotest.Adapter for the full interface.
----@class Adapter : neotest.Adapter
----@field name string
+--- See neotest.Adapter for the full interface.
+--- @class Adapter : neotest.Adapter
+--- @field name string
 M.Adapter = {
   name = "neotest-golang",
 }
 
----Find the project root directory given a current directory to work from.
----Should no root be found, the adapter can still be used in a non-project context if a test file matches.
----@async
----@param dir string @Directory to treat as cwd
----@return string | nil @Absolute root dir of test suite
+--- Find the project root directory given a current directory to work from.
+--- Should no root be found, the adapter can still be used in a non-project context if a test file matches.
+--- @async
+--- @param dir string @Directory to treat as cwd
+--- @return string | nil @Absolute root dir of test suite
 function M.Adapter.root(dir)
   -- Since neotest-golang is setting the cwd prior to running tests or debugging
   -- we can use the cwd as-is and treat it as the root.
   return dir
 end
 
----Filter directories when searching for test files
----@async
----@param name string Name of directory
----@param rel_path string Path to directory, relative to root
----@param root string Root directory of project
----@return boolean
+--- Filter directories when searching for test files
+--- @async
+--- @param name string Name of directory
+--- @param rel_path string Path to directory, relative to root
+--- @param root string Root directory of project
+--- @return boolean
 function M.Adapter.filter_dir(name, rel_path, root)
   local ignore_dirs = { ".git", "node_modules", ".venv", "venv" }
   for _, ignore in ipairs(ignore_dirs) do
@@ -45,17 +45,17 @@ function M.Adapter.filter_dir(name, rel_path, root)
   return true
 end
 
----@async
----@param file_path string
----@return boolean
+--- @async
+--- @param file_path string
+--- @return boolean
 function M.Adapter.is_test_file(file_path)
   return vim.endswith(file_path, "_test.go")
 end
 
----Given a file path, parse all the tests within it.
----@async
----@param file_path string Absolute file path
----@return neotest.Tree | nil
+--- Given a file path, parse all the tests within it.
+--- @async
+--- @param file_path string Absolute file path
+--- @return neotest.Tree | nil
 function M.Adapter.discover_positions(file_path)
   return ast.detect_tests(file_path)
 end
@@ -64,12 +64,12 @@ end
 ---NOTE: right now, this test function is delegating any test execution on
 ---a per-test basis.
 ---
----@param args neotest.RunArgs
----@return nil | neotest.RunSpec | neotest.RunSpec[]
+--- @param args neotest.RunArgs
+--- @return nil | neotest.RunSpec | neotest.RunSpec[]
 function M.Adapter.build_spec(args)
-  ---@type neotest.Tree
+  --- @type neotest.Tree
   local tree = args.tree
-  ---@type neotest.Position
+  --- @type neotest.Position
   local pos = args.tree:data()
 
   if not tree then
@@ -116,13 +116,13 @@ function M.Adapter.build_spec(args)
   end
 end
 
----Parse the test execution results, populate test outcome into the neotest
----node tree.
----@async
----@param spec neotest.RunSpec
----@param result neotest.StrategyResult
----@param tree neotest.Tree
----@return table<string, neotest.Result>
+--- Parse the test execution results, populate test outcome into the neotest
+--- node tree.
+--- @async
+--- @param spec neotest.RunSpec
+--- @param result neotest.StrategyResult
+--- @param tree neotest.Tree
+--- @return table<string, neotest.Result>
 function M.Adapter.results(spec, result, tree)
   if spec.context.test_type == "dir" then
     return results_dir.results(spec, result, tree)

lua/neotest-golang/json.lua

@@ -1,8 +1,8 @@
 local M = {}
 
 --- Process JSON and return objects of interest.
----@param raw_output table
----@return table
+--- @param raw_output table
+--- @return table
 function M.process_json(raw_output)
   local jsonlines = {}
   for _, line in ipairs(raw_output) do

lua/neotest-golang/options.lua

@@ -6,7 +6,7 @@ local M = {}
 
 --- Arguments to pass into `go test`. Will be combined with arguments required
 --- for neotest-golang to work and execute the expected test(s).
----@type table
+--- @type table
 M._go_test_args = {
   "-v",
   "-race",
@@ -15,11 +15,11 @@ M._go_test_args = {
 }
 
 --- Whether to enable nvim-dap-go.
----@type boolean
+--- @type boolean
 M._dap_go_enabled = false
 
 --- Options to pass into dap-go.setup.
----@type table
+--- @type table
 M._dap_go_opts = {}
 
 return M

lua/neotest-golang/results_dir.lua

@@ -2,47 +2,31 @@ local async = require("neotest.async")
 
 local convert = require("neotest-golang.convert")
 local json = require("neotest-golang.json")
+local utils = require("neotest-golang.utils")
 
 local M = {}
 
----@param spec neotest.RunSpec
----@param result neotest.StrategyResult
----@param tree neotest.Tree
+--- @param spec neotest.RunSpec
+--- @param result neotest.StrategyResult
+--- @param tree neotest.Tree
 function M.results(spec, result, tree)
-  ---@type table
+  --- The raw output from the 'go test' command.
+  --- @type table
   local raw_output = async.fn.readfile(result.output)
 
-  ---@type List<table>
+  --- The 'go test -json' output.
+  --- @type table
   local jsonlines = json.process_json(raw_output)
 
-  ---@type List
-  local full_test_output = {}
-
-  --- neotest results
-  ---@type table<string, neotest.Result>
-  local neotest_results = {}
-
-  --- internal results struct
-  ---@type table<string, table>
+  --- Internal table to hold all test result data.
+  --- @type table<string|table<string, string>, table>
   local internal_results = {}
 
   -- record neotest node data
   local duplicates = {}
   for idx, node in tree:iter_nodes() do
     local node_data = node:data()
 
-    if idx == 1 then
-      -- Example node:
-      -- {
-      --   id = "/Users/fredrik/code/public/neotest-golang/backend/internal/core/model",
-      --   name = "model",
-      --   path = "/Users/fredrik/code/public/neotest-golang/backend/internal/core/model",
-      --   type = "dir"
-      -- }
-
-      -- vim.notify(vim.inspect(node_data))
-    end
-
     if node_data.type == "test" then
       -- Example node:
       -- {
@@ -92,7 +76,7 @@ function M.results(spec, result, tree)
         ) -- TODO: would be nicer if this was handled by the common_parts function
 
         local match = nil
-        local partial_path = M.find_common_path(line.Package, folderpath)
+        local partial_path = utils.find_common_path(line.Package, folderpath)
 
         if partial_path ~= "" then
           local tweaked_neotest_node_id = neotest_node_id:gsub(" ", "_")
@@ -196,6 +180,9 @@ function M.results(spec, result, tree)
   end
 
   -- convert internal results to neotest results
+  --- Neotest results.
+  --- @type table<string, neotest.Result>
+  local neotest_results = {}
   for neotest_node_id in pairs(internal_results) do
     local test_properties = internal_results[neotest_node_id]
     local test_output_path = vim.fs.normalize(async.fn.tempname())
@@ -207,7 +194,8 @@ function M.results(spec, result, tree)
     }
   end
 
-  ---@type neotest.ResultStatus
+  --- Test command (e.g. 'go test') status.
+  --- @type neotest.ResultStatus
   local test_command_status = "skipped"
   if result.code == 0 then
     test_command_status = "passed"
@@ -216,6 +204,9 @@ function M.results(spec, result, tree)
   end
 
   -- write full test command output
+  --- Full 'go test' output (parsed from JSON).
+  --- @type table
+  local full_test_output = {}
   local parsed_output_path = vim.fs.normalize(async.fn.tempname())
   for _, line in ipairs(jsonlines) do
     -- vim.notify(vim.inspect(line))

lua/neotest-golang/results_test.lua

@@ -2,11 +2,11 @@ local async = require("neotest.async")
 
 local M = {}
 
----@async
----@param spec neotest.RunSpec
----@param result neotest.StrategyResult
----@param tree neotest.Tree
----@return table<string, neotest.Result>
+--- @async
+--- @param spec neotest.RunSpec
+--- @param result neotest.StrategyResult
+--- @param tree neotest.Tree
+--- @return table<string, neotest.Result>
 function M.results(spec, result, tree)
   if spec.context.skip then
     ---@type table<string, neotest.Result>
@@ -18,25 +18,25 @@ function M.results(spec, result, tree)
     return results
   end
 
-  ---@type neotest.ResultStatus
+  --- @type neotest.ResultStatus
   local result_status = "skipped"
   if result.code == 0 then
     result_status = "passed"
   else
     result_status = "failed"
   end
 
-  ---@type table
+  --- @type table
   local raw_output = async.fn.readfile(result.output)
 
-  ---@type string
+  --- @type string
   local test_filepath = spec.context.test_filepath
   local test_filename = vim.fn.fnamemodify(test_filepath, ":t")
-  ---@type List
+  --- @type table
   local test_result = {}
-  ---@type neotest.Error[]
+  --- @type neotest.Error[]
   local errors = {}
-  ---@type List<table>
+  --- @type table
   local jsonlines = require("neotest-golang.json").process_json(raw_output)
 
   for _, line in ipairs(jsonlines) do

lua/neotest-golang/runspec_dir.lua

@@ -3,8 +3,8 @@ local options = require("neotest-golang.options")
 local M = {}
 
 --- Build runspec for a directory.
----@param pos neotest.Position
----@return neotest.RunSpec | nil
+--- @param pos neotest.Position
+--- @return neotest.RunSpec | nil
 function M.build(pos)
   -- Strategy:
   -- 1. Find the go.mod file from pos.path.
@@ -56,18 +56,18 @@ function M.remove_base_path(base_path, target_path)
 end
 
 --- Build runspec for a directory of tests
----@param pos neotest.Position
----@param cwd string
----@param test_pattern string
----@return neotest.RunSpec
+--- @param pos neotest.Position
+--- @param cwd string
+--- @param test_pattern string
+--- @return neotest.RunSpec
 function M.build_dir_test_runspec(pos, cwd, test_pattern)
   local gotest = {
     "go",
     "test",
     "-json",
   }
 
-  ---@type table
+  --- @type table
   local go_test_args = {
     test_pattern,
   }
@@ -76,7 +76,7 @@ function M.build_dir_test_runspec(pos, cwd, test_pattern)
     vim.list_extend(vim.deepcopy(options._go_test_args), go_test_args)
   local gotest_command = vim.list_extend(vim.deepcopy(gotest), combined_args)
 
-  ---@type neotest.RunSpec
+  --- @type neotest.RunSpec
   local run_spec = {
     command = gotest_command,
     cwd = cwd,

lua/neotest-golang/runspec_test.lua

@@ -4,13 +4,13 @@ local options = require("neotest-golang.options")
 local M = {}
 
 --- Build runspec for a single test
----@param pos neotest.Position
----@param strategy string
----@return neotest.RunSpec
+--- @param pos neotest.Position
+--- @param strategy string
+--- @return neotest.RunSpec
 function M.build(pos, strategy)
-  ---@type string
+  --- @type string
   local test_name = convert.to_gotest_test_name(pos.id)
-  ---@type string
+  --- @type string
   local test_folder_absolute_path = string.match(pos.path, "(.+)/")
 
   local gotest = {
@@ -19,7 +19,7 @@ function M.build(pos, strategy)
     "-json",
   }
 
-  ---@type table
+  --- @type table
   local go_test_args = {
     test_folder_absolute_path,
     "-run",
@@ -30,7 +30,7 @@ function M.build(pos, strategy)
     vim.list_extend(vim.deepcopy(options._go_test_args), go_test_args)
   local gotest_command = vim.list_extend(vim.deepcopy(gotest), combined_args)
 
-  ---@type neotest.RunSpec
+  --- @type neotest.RunSpec
   local run_spec = {
     command = gotest_command,
     cwd = test_folder_absolute_path,
@@ -66,8 +66,8 @@ function M.build(pos, strategy)
   return run_spec
 end
 
----@param test_name string
----@return table | nil
+--- @param test_name string
+--- @return table | nil
 function M.get_dap_config(test_name)
   -- :help dap-configuration
   local dap_config = {

lua/neotest-golang/utils.lua

@@ -1,8 +1,8 @@
 local M = {}
 
----Check if a table is empty.
----@param t table
----@return boolean
+--- Check if a table is empty.
+--- @param t table
+--- @return boolean
 function M.table_is_empty(t)
   return next(t) == nil
 end