olexsmir/gopher.nvim
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs: update (#103)

Browse source 
* 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
This commit is contained in:
Smirnov Oleksandr 2025-03-23 15:34:47 +02:00 • committed by Oleksandr Smirnov
parent 592fe82760
commit c0b2834652
No known key found for this signature in database
13 changed files with 107 additions and 112 deletions
Download patch file Download diff file Expand all files Collapse all files

5
README.md
View file

@ -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

82
doc/gopher.nvim.txt
View file

@ -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|
Install dependencies..............................|gopher.nvim-install-deps|
Configuration...........................................|gopher.nvim-config|
Setup..................................................|gopher.nvim-setup()|
Install dependencies..............................|gopher.nvim-dependencies|
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
------------------------------------------------------------------------------
*gopher.nvim-gotests-named*
You can enable named tests in the config if you prefer using named tests.
See |gopher.nvim-config|.
If you prefer named tests, you can enable them in |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:

8
lua/gopher/_utils/init.lua
View file

@ -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

1
lua/gopher/_utils/log.lua
View file

@ -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

10
lua/gopher/comment.lua
View file

@ -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 This module provides a way to generate comments for Go code.
---@text
--- 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

24
lua/gopher/config.lua
View file

@ -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 {
---@tag gopher.nvim-config-defaults
---@toc_entry Config
---@tag gopher.nvim-config
---@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

8
lua/gopher/gotests.lua
View file

@ -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
---
---@tag gopher.nvim-gotests-named
---@text
--- You can enable named tests in the config if you prefer using named tests.
--- See |gopher.nvim-config|.
--- If you prefer named tests, you can enable them in |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")

8
lua/gopher/iferr.lua
View file

@ -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]

7
lua/gopher/impl.lua
View file

@ -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.
---@usage
--- 1. Automatically implement an interface for a struct:
---@text
--- 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`
--- - This will automatically determine the receiver and implement the `io.Reader` interface.

19
lua/gopher/init.lua
View file

@ -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)
---@param user_config gopher.Config
---@usage >lua
--- 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.

27
lua/gopher/struct_tags.lua
View file

@ -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()

4
scripts/docgen.lua
View file

@ -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 })

16
spec/unit/utils_test.lua
View file

@ -1,15 +1,6 @@
local t = require "spec.testutils"
local child = MiniTest.new_child_neovim()
local T = MiniTest.new_set {
hooks = {
post_once = child.stop,
pre_case = function()
child.restart { "-u", t.mininit_path }
end,
},
}
local _, T = t.setup "utils"
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