docs: update (#103)

* chore: add @dochide annotation

- it's easier to distinguish @private and something i dont want to see in docs

* docs: update

* refactor: move thing out to utils

* fix: lua-ls error

* fixup! refactor: move thing out to utils

* docs: update

README.md

@@ -29,7 +29,7 @@ Requirements:
     vim.cmd.GoInstallDeps()
   end,
   ---@type gopher.Config
-  opts = {}, -- required
+  opts = {},
 }
 ```
 
@@ -39,10 +39,11 @@ Requirements:
 >
 > If you need more info look `:h gopher.nvim`
 
-**Take a look at default options (might be a bit outdated, look `:h gopher.nvim-config-defaults`)**
+**Take a look at default options (might be a bit outdated, look `:h gopher.nvim-config`)**
 
 ```lua
 require("gopher").setup {
+  -- log level, you might consider using DEBUG or TRACE for debugging the plugin
   log_level = vim.log.levels.INFO,
 
   -- timeout for running internal commands

doc/gopher.nvim.txt

@@ -1,16 +1,16 @@
-*gopher.nvim*
+*gopher.nvim* Enhance your golang experience
+
+MIT License Copyright (c) 2025 Oleksandr Smirnov
 
 ==============================================================================
 
 gopher.nvim is a minimalistic plugin for Go development in Neovim written in Lua.
 It's not an LSP tool, the main goal of this plugin is add go tooling support in Neovim.
 
-------------------------------------------------------------------------------
-                                                 *gopher.nvim-table-of-contents*
 Table of Contents
-  Setup....................................................|gopher.nvim-setup|
+  Setup..................................................|gopher.nvim-setup()|
-  Install dependencies..............................|gopher.nvim-install-deps|
+  Install dependencies..............................|gopher.nvim-dependencies|
-  Configuration...........................................|gopher.nvim-config|
+  Config..................................................|gopher.nvim-config|
   Commands..............................................|gopher.nvim-commands|
   Modify struct tags.................................|gopher.nvim-struct-tags|
   Auto implementation of interface methods..................|gopher.nvim-impl|
@@ -19,20 +19,22 @@ Table of Contents
   Generate comments.....................................|gopher.nvim-comments|
 
 ------------------------------------------------------------------------------
-                                                             *gopher.nvim-setup*
+                                                           *gopher.nvim-setup()*
                          `gopher.setup`({user_config})
 Setup function. This method simply merges default config with opts table.
 You can read more about configuration at |gopher.nvim-config|
 Calling this function is optional, if you ok with default settings.
-See |gopher.nvim.config-defaults|
+See |gopher.nvim.config|
 
 Usage ~
-`require("gopher").setup {}` (replace `{}` with your `config` table)
+>lua
+ require("gopher").setup {} -- use default config or replace {} with your own
+<
 Parameters ~
-{user_config} `(gopher.Config)`
+{user_config} `(gopher.Config)` See |gopher.nvim-config|
 
 ------------------------------------------------------------------------------
-                                                      *gopher.nvim-install-deps*
+                                                      *gopher.nvim-dependencies*
                              `gopher.install_deps`
 Gopher.nvim implements most of its features using third-party tools.
 To install these tools, you can run `:GoInstallDeps` command
@@ -44,17 +46,9 @@ to install them synchronously pass `{sync = true}` as an argument.
 ==============================================================================
 ------------------------------------------------------------------------------
                                                             *gopher.nvim-config*
-config it is the place where you can configure the plugin.
-also this is optional is you're ok with default settings.
-You can look at default options |gopher.nvim-config-defaults|
-
-------------------------------------------------------------------------------
-                                                   *gopher.nvim-config-defaults*
                                 `default_config`
 >lua
   local default_config = {
-    --minidoc_replace_end
-
     -- log level, you might consider using DEBUG or TRACE for debugging the plugin
     ---@type number
     log_level = vim.log.levels.INFO,
@@ -112,15 +106,18 @@ you can set `vim.g.gopher_register_commands` to `false`, before loading the plug
 ==============================================================================
 ------------------------------------------------------------------------------
                                                        *gopher.nvim-struct-tags*
-struct-tags is utilizing the `gomodifytags` tool to add or remove tags to struct fields.
+
+`struct_tags` is utilizing the `gomodifytags` tool to add or remove tags to struct fields.
+
 Usage ~
 
 How to add/remove tags to struct fields:
-
+1. Place cursor on the struct
-------------------------------------------------------------------------------
 2. Run `:GoTagAdd json` to add json tags to struct fields
 3. Run `:GoTagRm json` to remove json tags to struct fields
 
+To clear all tags from struct run: `:GoTagClear`
+
 NOTE: if you dont specify the tag it will use `json` as default
 
 Example:
@@ -139,32 +136,14 @@ Example:
        Name string `yaml:name`
    }
 <
-------------------------------------------------------------------------------
-                                                             *struct_tags.add()*
-                            `struct_tags.add`({...})
-tags to a struct under the cursor
-Parameters ~
-{...} `(string)` Tags to add to the struct fields. If not provided, it will use [config.gotag.default_tag]
-
-------------------------------------------------------------------------------
-                                                          *struct_tags.remove()*
-                          `struct_tags.remove`({...})
-tags from a struct under the cursor
-Parameters ~
-{...} `(string)` Tags to add to the struct fields. If not provided, it will use [config.gotag.default_tag]
-
-------------------------------------------------------------------------------
-                                                           *struct_tags.clear()*
-                             `struct_tags.clear`()
-all tags from a struct under the cursor
-
 
 ==============================================================================
 ------------------------------------------------------------------------------
                                                               *gopher.nvim-impl*
-impl is utilizing the `impl` tool to generate method stubs for interfaces.
-Usage ~
 
+Integration of `impl` tool to generate method stubs for interfaces.
+
+Usage ~
 1. Automatically implement an interface for a struct:
    - Place your cursor on the struct where you want to implement the interface.
    - Run `:GoImpl io.Reader`
@@ -214,17 +193,16 @@ Usage ~
 You can also specify the template to use for generating the tests. See |gopher.nvim-config|
 More details about templates can be found at: https://github.com/cweill/gotests
 
-------------------------------------------------------------------------------
+If you prefer named tests, you can enable them in |gopher.nvim-config|.
-                                                     *gopher.nvim-gotests-named*
-
-You can enable named tests in the config if you prefer using named tests.
-See |gopher.nvim-config|.
 
 
 ==============================================================================
 ------------------------------------------------------------------------------
                                                              *gopher.nvim-iferr*
-If you're using `iferr` tool, this module provides a way to automatically insert `if err != nil` check.
+
+`iferr` provides a way to way to automatically insert `if err != nil` check.
+If you want to change `-message` option of `iferr` tool, see |gopher.nvim-config|
+
 Usage ~
 Execute `:GoIfErr` near any `err` variable to insert the check
 
@@ -232,9 +210,11 @@ Execute `:GoIfErr` near any `err` variable to insert the check
 ==============================================================================
 ------------------------------------------------------------------------------
                                                           *gopher.nvim-comments*
-Usage ~
+
-Execute `:GoCmt` to generate a comment for the current function/method/struct/etc on this line.
 This module provides a way to generate comments for Go code.
 
+Usage ~
+Set cursor on line with function/method/struct/etc and run `:GoCmt` to generate a comment.
+
 
  vim:tw=78:ts=8:noet:ft=help:norl:

lua/gopher/_utils/init.lua

@@ -7,6 +7,7 @@ local utils = {}
 function utils.notify(msg, lvl)
   lvl = lvl or vim.log.levels.INFO
   vim.notify(msg, lvl, {
+    ---@diagnostic disable-next-line:undefined-field
     title = c.___plugin_name,
   })
   log.debug(msg)
@@ -30,4 +31,11 @@ function utils.remove_empty_lines(t)
   return res
 end
 
+---@param s string
+---@return string
+function utils.trimend(s)
+  local r, _ = string.gsub(s, "%s+$", "")
+  return r
+end
+
 return utils

lua/gopher/_utils/log.lua

@@ -18,6 +18,7 @@ local c = require "gopher.config"
 
 local config = {
   -- Name of the plugin. Prepended to log messages
+  ---@diagnostic disable-next-line:undefined-field
   name = c.___plugin_name,
 
   -- Should print the output to neovim while running

lua/gopher/comment.lua

@@ -1,7 +1,9 @@
 ---@toc_entry Generate comments
 ---@tag gopher.nvim-comments
----@usage Execute `:GoCmt` to generate a comment for the current function/method/struct/etc on this line.
+---@text
----@text This module provides a way to generate comments for Go code.
+--- This module provides a way to generate comments for Go code.
+---
+---@usage Set cursor on line with function/method/struct/etc and run `:GoCmt` to generate a comment.
 
 local ts = require "gopher._utils.ts"
 local log = require "gopher._utils.log"
@@ -9,14 +11,14 @@ local comment = {}
 
 ---@param name string
 ---@return string
----@private
+---@dochide
 local function template(name)
   return "// " .. name .. " "
 end
 
 ---@param bufnr integer
 ---@return string
----@private
+---@dochide
 local function generate(bufnr)
   local s_ok, s_res = pcall(ts.get_struct_under_cursor, bufnr)
   if s_ok then

lua/gopher/config.lua

@@ -1,17 +1,9 @@
----@toc_entry Configuration
----@tag gopher.nvim-config
----@text config it is the place where you can configure the plugin.
---- also this is optional is you're ok with default settings.
---- You can look at default options |gopher.nvim-config-defaults|
-
----@type gopher.Config
----@private
 local config = {}
 
 ---@tag gopher.nvim-config.ConfigGoTagTransform
 ---@text Possible values for |gopher.Config|.gotag.transform:
 ---
----@private
+---@dochide
 ---@alias gopher.ConfigGoTagTransform
 ---| "snakecase"  "GopherUser" -> "gopher_user"
 ---| "camelcase"  "GopherUser" -> "gopherUser"
@@ -20,15 +12,11 @@ local config = {}
 ---| "titlecase"  "GopherUser" -> "Gopher User"
 ---| "keep"       keeps the original field name
 
---minidoc_replace_start {
+---@toc_entry Config
-
+---@tag gopher.nvim-config
----@tag gopher.nvim-config-defaults
 ---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)
----
 ---@class gopher.Config
 local default_config = {
-  --minidoc_replace_end
-
   -- log level, you might consider using DEBUG or TRACE for debugging the plugin
   ---@type number
   log_level = vim.log.levels.INFO,
@@ -73,7 +61,7 @@ local default_config = {
 --minidoc_afterlines_end
 
 ---@type gopher.Config
----@private
+---@dochide
 local _config = default_config
 
 -- I am kinda secret so don't tell anyone about me even dont use me
@@ -84,7 +72,7 @@ local _config = default_config
 _config.___plugin_name = "gopher.nvim" ---@diagnostic disable-line: inject-field
 
 ---@param user_config? gopher.Config
----@private
+---@dochide
 function config.setup(user_config)
   vim.validate { user_config = { user_config, "table", true } }
 
@@ -117,6 +105,6 @@ setmetatable(config, {
   end,
 })
 
+---@dochide
 ---@return gopher.Config
----@private
 return config

lua/gopher/gotests.lua

@@ -15,11 +15,7 @@
 --- You can also specify the template to use for generating the tests. See |gopher.nvim-config|
 --- More details about templates can be found at: https://github.com/cweill/gotests
 ---
-
+--- If you prefer named tests, you can enable them in |gopher.nvim-config|.
----@tag gopher.nvim-gotests-named
----@text
---- You can enable named tests in the config if you prefer using named tests.
---- See |gopher.nvim-config|.
 
 local c = require "gopher.config"
 local ts_utils = require "gopher._utils.ts"
@@ -29,7 +25,7 @@ local log = require "gopher._utils.log"
 local gotests = {}
 
 ---@param args table
----@private
+---@dochide
 local function add_test(args)
   if c.gotests.named then
     table.insert(args, "-named")

lua/gopher/iferr.lua

@@ -1,6 +1,11 @@
+-- Thanks https://github.com/koron/iferr for vim implementation
+
 ---@toc_entry Iferr
 ---@tag gopher.nvim-iferr
----@text If you're using `iferr` tool, this module provides a way to automatically insert `if err != nil` check.
+---@text
+--- `iferr` provides a way to way to automatically insert `if err != nil` check.
+--- If you want to change `-message` option of `iferr` tool, see |gopher.nvim-config|
+---
 ---@usage Execute `:GoIfErr` near any `err` variable to insert the check
 
 local c = require "gopher.config"
@@ -9,7 +14,6 @@ local r = require "gopher._utils.runner"
 local log = require "gopher._utils.log"
 local iferr = {}
 
--- That's Lua implementation: https://github.com/koron/iferr
 function iferr.iferr()
   local curb = vim.fn.wordcount().cursor_bytes
   local pos = vim.fn.getcurpos()[2]

lua/gopher/impl.lua

@@ -1,8 +1,9 @@
 ---@toc_entry Auto implementation of interface methods
 ---@tag gopher.nvim-impl
----@text impl is utilizing the `impl` tool to generate method stubs for interfaces.
+---@text
----@usage
+--- Integration of `impl` tool to generate method stubs for interfaces.
---- 1. Automatically implement an interface for a struct:
+---
+---@usage 1. Automatically implement an interface for a struct:
 ---    - Place your cursor on the struct where you want to implement the interface.
 ---    - Run `:GoImpl io.Reader`
 ---    - This will automatically determine the receiver and implement the `io.Reader` interface.

lua/gopher/init.lua

@@ -1,12 +1,13 @@
---- *gopher.nvim*
+--- *gopher.nvim* Enhance your golang experience
+---
+--- MIT License Copyright (c) 2025 Oleksandr Smirnov
 ---
 --- ==============================================================================
 ---
 --- gopher.nvim is a minimalistic plugin for Go development in Neovim written in Lua.
 --- It's not an LSP tool, the main goal of this plugin is add go tooling support in Neovim.
-
+---
 --- Table of Contents
----@tag gopher.nvim-table-of-contents
 ---@toc
 
 local log = require "gopher._utils.log"
@@ -16,14 +17,16 @@ local gocmd = require("gopher._utils.gocmd").run
 local gopher = {}
 
 ---@toc_entry Setup
----@tag gopher.nvim-setup
+---@tag gopher.nvim-setup()
 ---@text Setup function. This method simply merges default config with opts table.
 --- You can read more about configuration at |gopher.nvim-config|
 --- Calling this function is optional, if you ok with default settings.
---- See |gopher.nvim.config-defaults|
+--- See |gopher.nvim.config|
 ---
----@usage `require("gopher").setup {}` (replace `{}` with your `config` table)
+---@usage >lua
----@param user_config gopher.Config
+---  require("gopher").setup {} -- use default config or replace {} with your own
+--- <
+---@param user_config gopher.Config See |gopher.nvim-config|
 gopher.setup = function(user_config)
   log.debug "setting up config"
   require("gopher.config").setup(user_config)
@@ -31,7 +34,7 @@ gopher.setup = function(user_config)
 end
 
 ---@toc_entry Install dependencies
----@tag gopher.nvim-install-deps
+---@tag gopher.nvim-dependencies
 ---@text Gopher.nvim implements most of its features using third-party tools.
 --- To install these tools, you can run `:GoInstallDeps` command
 --- or call `require("gopher").install_deps()` if you want to use lua api.

lua/gopher/struct_tags.lua

@@ -1,12 +1,16 @@
 ---@toc_entry Modify struct tags
 ---@tag gopher.nvim-struct-tags
----@text struct-tags is utilizing the `gomodifytags` tool to add or remove tags to struct fields.
+---@text
+--- `struct_tags` is utilizing the `gomodifytags` tool to add or remove tags to struct fields.
+---
 ---@usage
 --- How to add/remove tags to struct fields:
---  1. Place cursor on the struct
+--- 1. Place cursor on the struct
 --- 2. Run `:GoTagAdd json` to add json tags to struct fields
 --- 3. Run `:GoTagRm json` to remove json tags to struct fields
 ---
+--- To clear all tags from struct run: `:GoTagClear`
+---
 --- NOTE: if you dont specify the tag it will use `json` as default
 ---
 --- Example:
@@ -29,13 +33,14 @@
 local ts = require "gopher._utils.ts"
 local r = require "gopher._utils.runner"
 local c = require "gopher.config"
+local u = require "gopher._utils"
 local log = require "gopher._utils.log"
 local struct_tags = {}
 
 ---@param fpath string
 ---@param bufnr integer
 ---@param user_args string[]
----@private
+---@dochide
 local function handle_tags(fpath, bufnr, user_args)
   local st = ts.get_struct_under_cursor(bufnr)
 
@@ -73,7 +78,7 @@ local function handle_tags(fpath, bufnr, user_args)
   end
 
   for i, v in ipairs(res["lines"]) do
-    res["lines"][i] = string.gsub(v, "%s+$", "")
+    res["lines"][i] = u.trimend(v)
   end
 
   vim.api.nvim_buf_set_lines(
@@ -87,7 +92,7 @@ end
 
 ---@param args string[]
 ---@return string
----@private
+---@dochide
 local function handler_user_args(args)
   if #args == 0 then
     return c.gotag.default_tag
@@ -95,8 +100,10 @@ local function handler_user_args(args)
   return table.concat(args, ",")
 end
 
----Adds tags to a struct under the cursor
+-- Adds tags to a struct under the cursor
+-- See |gopher.nvim-struct-tags|
 ---@param ... string Tags to add to the struct fields. If not provided, it will use [config.gotag.default_tag]
+---@dochide
 function struct_tags.add(...)
   local args = { ... }
   local fpath = vim.fn.expand "%"
@@ -106,7 +113,9 @@ function struct_tags.add(...)
   handle_tags(fpath, bufnr, { "-add-tags", user_tags })
 end
 
----Removes tags from a struct under the cursor
+-- Removes tags from a struct under the cursor
+-- See `:h gopher.nvim-struct-tags`
+---@dochide
 ---@param ... string Tags to add to the struct fields. If not provided, it will use [config.gotag.default_tag]
 function struct_tags.remove(...)
   local args = { ... }
@@ -117,7 +126,9 @@ function struct_tags.remove(...)
   handle_tags(fpath, bufnr, { "-remove-tags", user_tags })
 end
 
----Removes all tags from a struct under the cursor
+-- Removes all tags from a struct under the cursor
+-- See `:h gopher.nvim-struct-tags`
+---@dochide
 function struct_tags.clear()
   local fpath = vim.fn.expand "%"
   local bufnr = vim.api.nvim_get_current_buf()

scripts/docgen.lua

@@ -30,4 +30,8 @@ hooks.write_pre = function(lines)
   return lines
 end
 
+hooks.sections["@dochide"] = function(s)
+  s.parent:clear_lines()
+end
+
 MiniDoc.generate(files, "doc/gopher.nvim.txt", { hooks = hooks })

spec/unit/utils_test.lua

@@ -1,15 +1,6 @@
 local t = require "spec.testutils"
-local child = MiniTest.new_child_neovim()
+local _, T = t.setup "utils"
-local T = MiniTest.new_set {
-  hooks = {
-    post_once = child.stop,
-    pre_case = function()
-      child.restart { "-u", t.mininit_path }
-    end,
-  },
-}
 
-T["utils"] = MiniTest.new_set()
 T["utils"]["should .remove_empty_lines()"] = function()
   local u = require "gopher._utils"
   local inp = { "hi", "", "a", "", "", "asdf" }
@@ -26,4 +17,9 @@ T["utils"]["should .readfile_joined()"] = function()
   t.eq(u.readfile_joined(tmp), data)
 end
 
+T["utils"]["should .trimend()"] = function()
+  local u = require "gopher._utils"
+  t.eq(u.trimend "  hi   ", "  hi")
+end
+
 return T