From 10cec9c6b0156c76f8d30d8aaba5f3d3afe9129c Mon Sep 17 00:00:00 2001 From: Smirnov Oleksandr Date: Thu, 4 Apr 2024 17:15:55 +0300 Subject: [PATCH] add help file, and docs (#59) * idk how good this idea is * this could be working but i still cant figure out how to run it * ignore tags that mini.doc gens, but why? * chore(taskfile): force exiting after tests because i got infinit ci * chore(ci): add more nvim versions to run on * chore: update taskfile * feat: add docs generator * docs: its only begining * refactor: update docgen script * docs: write some more * docs(config): update * docs: update readme * language * hope it would work * what about that? * maybe this would work? * update md * upd * WHY DOESNT IT WORKING * idk by but 0.9.3 just fails the ci, so i deleted it from suite * again update, why does markdown not work in embeded html * maybe it can help? * upd * again update * kinda fix * fix: formatting * again some updating * some readme updating * fix, this shouldnt be in repo * i finnaly undertood how to fix this fking skill issue * fix(struct_tags): typo * refactor(docs): change the order in generated file * docs: install deps * refactor(scripts): rename doc-gen script * docs(impl): write docs * docs(dap): add doc * stylua . * docs(struct_tags): add doc * docs(gotests): add docs * docs(iferr): add docs * docs(comment): add doc * update CONTRIBUTING.md * docs(README): talk about `develop` branch * docs: update README.md --- .github/workflows/tests.yml | 14 +- CONTRIBUTING.md | 48 +++++- README.md | 266 ++++++++++++++++------------- Taskfile.yml | 39 +++-- doc/.gitignore | 1 + doc/gopher.nvim.txt | 220 ++++++++++++++++++++++++ lua/gopher/comment.lua | 5 + lua/gopher/config.lua | 22 ++- lua/gopher/dap.lua | 7 +- lua/gopher/gotests.lua | 48 +++++- lua/gopher/iferr.lua | 7 +- lua/gopher/impl.lua | 29 ++++ lua/gopher/init.lua | 25 +++ lua/gopher/struct_tags.lua | 34 +++- scripts/docgen.lua | 33 ++++ {spec => scripts}/minimal_init.lua | 1 + 16 files changed, 657 insertions(+), 142 deletions(-) create mode 100644 doc/.gitignore create mode 100644 doc/gopher.nvim.txt create mode 100644 scripts/docgen.lua rename {spec => scripts}/minimal_init.lua (93%) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 9ffb99c..09fb168 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -16,11 +16,20 @@ jobs: - v0.8.3 - v0.9.0 - v0.9.1 + - v0.9.2 + - v0.9.4 + - v0.9.5 runs-on: ${{ matrix.os }} steps: + - name: Install Task + uses: arduino/setup-task@v1 + with: + version: 3.x + repo-token: ${{ secrets.GITHUB_TOKEN }} + - uses: actions/checkout@v3 + - name: Install Neovim - shell: bash run: | mkdir -p /tmp/nvim wget -q https://github.com/neovim/neovim/releases/download/${{ matrix.nvim_version }}/nvim.appimage -O /tmp/nvim/nvim.appimage @@ -28,7 +37,8 @@ jobs: chmod a+x ./nvim.appimage ./nvim.appimage --appimage-extract echo "/tmp/nvim/squashfs-root/usr/bin/" >> $GITHUB_PATH + - name: Run Tests run: | nvim --version - nvim --headless -u ./spec/minimal_init.lua -c "PlenaryBustedDirectory spec {minimal_init='./spec/minimal_init.lua', sequential=true}" + task test diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3a3c7b..39092b1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,14 @@ # Contributing to `gopher.nvim` -Thank you for looking to contributing +Thank you for taking the time to submit some code to gopher.nvim. It means a lot! + +### Task running + +In this codebase for running tasks is used [Taskfile](https://taskfile.dev). +You can install it with: +```bash +go install github.com/go-task/task/v3/cmd/task@latest +``` ### Styling and formatting @@ -8,6 +16,40 @@ Code is formatted by [stylua](https://github.com/JohnnyMorganz/StyLua) and linte You can install these with: ```bash -cargo install stylua -cargo install selene +sudo pacman -S selene stylua +# or whatever is your package manager +# or way of installing pkgs +``` + +For formatting use this following commands, or setup your editor to integrate with selene/stylua: +```bash +task format +task format:check # will check if your code formatted +task lint +``` + +### Documentation + +Here we are using [mini.doc](https://github.com/echasnovski/mini.nvim/blob/main/readmes/mini-doc.md) +for generating help files based on EmmyLua-like annotations in comments + +You can generate docs with: +```bash +task docgen +``` + +### Commit messages +We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), please follow it. + +### Testing + +For testing this plugins uses [plenary.nvim](https://github.com/nvim-lua/plenary.nvim). +All tests live in [/spec](https://github.com/olexsmir/gopher.nvim/tree/main/spec) dir. + +You can run tests with: +```bash +task test +# also there are some aliases for that +task tests +task spec ``` diff --git a/README.md b/README.md index 3079257..f105a58 100644 --- a/README.md +++ b/README.md @@ -4,40 +4,54 @@ 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. +It's **NOT** an LSP tool, the main goal of this plugin is to add go tooling support in Neovim. -## Install +> If you want to use new and maybe undocumented, and unstable features you might use [develop](https://github.com/olexsmir/gopher.nvim/tree/develop) branch. -Pre-dependency: [go](https://github.com/golang/go) (tested on 1.17 and 1.18) +## Install (using [lazy.nvim](https://github.com/folke/lazy.nvim)) + +Pre-dependency: + +- [Go](https://github.com/golang/go) +- `go` treesitter parser, install by `:TSInstall go` ```lua -use { +{ "olexsmir/gopher.nvim", - requires = { -- dependencies + ft = "go", + -- branch = "develop", -- if you want develop branch + -- keep in mind, it might break everything + dependencies = { "nvim-lua/plenary.nvim", "nvim-treesitter/nvim-treesitter", + "mfussenegger/nvim-dap", -- (optional) only if you use `gopher.dap` }, + -- (optional) will update plugin's deps on every update + build = function() + vim.cmd.GoInstallDeps() + end, + ---@type gopher.Config + opts = {}, } ``` -Also, run `TSInstall go` if `go` parser if isn't installed yet. +## Configuratoin -## Config +> [!IMPORTANT] +> +> If you need more info look `:h gopher.nvim` -By `.setup` function you can configure the plugin. - -Note: - -- `installer` does not install the tool in user set path +**Take a look at default options** ```lua require("gopher").setup { commands = { go = "go", gomodifytags = "gomodifytags", - gotests = "~/go/bin/gotests", -- also you can set custom command path + gotests = "gotests", impl = "impl", iferr = "iferr", + dlv = "dlv", }, gotests = { -- gotests doesn't have template named "default" so this plugin uses "default" to set the default template @@ -48,151 +62,170 @@ require("gopher").setup { -- works only with gotests installed from develop branch named = false, }, + gotag = { + transform = "snakecase", + }, } ``` -### Named tests with testify (using map instead of slice for test cases) - -```lua -require("gopher").setup({ - gotests = { - template = "testify", - named = true - } -}) -``` - -For named tests to work you have to install gotests from develop branch, for example using [mason-tool-installer](https://github.com/WhoIsSethDaniel/mason-tool-installer.nvim): - -```lua - require('mason-tool-installer').setup({ - ensure_installed = { - { "gotests", version = "develop" }, - } -}) -``` - -Or by calling `vim.fn.jobstart`: - -```lua -vim.fn.jobstart("go install github.com/cweill/gotests/...@develop") -``` - -If you're using `lazy.nvim` you can put in `build` function inside `setup()` - ## Features -1. Installation requires this go tool: + -```vim -:GoInstallDeps -``` +
+ + Install plugin's go deps + -It will install next tools: + ```vim + :GoInstallDeps + ``` -- [gomodifytags](https://github.com/fatih/gomodifytags) -- [impl](https://github.com/josharian/impl) -- [gotests](https://github.com/cweill/gotests) -- [iferr](https://github.com/koron/iferr) + This will install the following tools: + + - [gomodifytags](https://github.com/fatih/gomodifytags) + - [impl](https://github.com/josharian/impl) + - [gotests](https://github.com/cweill/gotests) + - [iferr](https://github.com/koron/iferr) + - [dlv](github.com/go-delve/delve/cmd/dlv) +
+ +
+ + Add and remove tags for structs via gomodifytags + -2. Modify struct tags: By default `json` tag will be added/removed, if not set: -```vim -:GoTagAdd json " For add json tag -:GoTagRm yaml " For remove yaml tag -``` + ```vim + " add json tag + :GoTagAdd json -3. Run `go mod` command: + " remove yaml tag + :GoTagRm yaml + ``` -```vim -:GoMod tidy " Runs `go mod tidy` -:GoMod init asdf " Runs `go mod init asdf` -``` + ```lua + -- or you can use lua api + require("gopher").tags.add "xml" + require("gopher").tags.rm "proto" + ``` +
-4. Run `go get` command +
+ + Generating tests via gotests + -Link can have a `http` or `https` prefix. + ```vim + " Generate one test for a specific function/method(one under cursor) + :GoTestAdd -You can provide more than one package url: + " Generate all tests for all functions/methods in the current file + :GoTestsAll -```vim -:GoGet github.com/gorilla/mux -``` + " Generate tests for only exported functions/methods in the current file + :GoTestsExp + ``` -5. Interface implementation + ```lua + -- or you can use lua api + require("gopher").test.add() + require("gopher").test.exported() + require("gopher").test.all() + ``` -Command syntax: + For named tests see `:h gopher.nvim-gotests-named` +
-```vim -:GoImpl [receiver] [interface] +
+ + Run commands like go mod/get/etc inside of nvim + -" Also you can put cursor on the struct and run: -:GoImpl [interface] -``` + ```vim + :GoGet github.com/gorilla/mux -Example of usage: + " Link can have an `http` or `https` prefix. + :GoGet https://github.com/lib/pq -```vim -" Example -:GoImpl r Read io.Reader -" or simply put your cursor in the struct and run: -:GoImpl io.Reader -``` + " You can provide more than one package url + :GoGet github.com/jackc/pgx/v5 github.com/google/uuid/ -6. Generate tests with [gotests](https://github.com/cweill/gotests) + " go mod commands + :GoMod tidy + :GoMod init new-shiny-project -Generate one test for a specific function/method: + " go work commands + :GoWork sync -```vim -:GoTestAdd -``` + " run go generate in cwd + :GoGenerate -Generate all tests for all functions/methods in current file: + " run go generate for the current file + :GoGenerate % + ``` +
-```vim -:GoTestsAll -``` +
+ + Interface implementation via impl + -Generate tests only for exported functions/methods in current file: + Syntax of the command: + ```vim + :GoImpl [receiver] [interface] -```vim -:GoTestsExp -``` + " also you can put a cursor on the struct and run + :GoImpl [interface] + ``` -7. Run `go generate` command; + Usage examples: + ```vim + :GoImpl r Read io.Reader + :GoImpl Write io.Writer -```vim -" Run `go generate` in cwd path -:GoGenerate + " or you can simply put a cursor on the struct and run + :GoImpl io.Reader + ``` +
-" Run `go generate` for current file -:GoGenerate % -``` +
+ + Generate boilerplate for doc comments + -8. Generate doc comment + First set a cursor on **public** package/function/interface/struct and execute: -First set a cursor on **public** package/function/interface/struct and execute: + ```vim + :GoCmt + ``` +
-```vim -:GoCmt -``` -9. Generate `if err` +
+ + Generate if err != nil { via iferr + -Set cursor on the line with **err** and execute: + Set the cursor on the line with `err` and execute -```vim -:GoIfErr -``` + ```vim + :GoIfErr + ``` +
-10. Setup nvim-dap for go in one line. +
+ + Setup nvim-dap for go in one line + -Notice: [nvim-dap](https://github.com/mfussenegger/nvim-dap) is required + note [nvim-dap](https://github.com/mfussenegger/nvim-dap) has to be installed -```lua -require"gopher.dap".setup() -``` + ```lua + require("gopher.dap").setup() + ``` +
## Contributing @@ -202,3 +235,4 @@ PRs are always welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) - [go.nvim](https://github.com/ray-x/go.nvim) - [nvim-dap-go](https://github.com/leoluz/nvim-dap-go) +- [iferr](https://github.com/koron/iferr) diff --git a/Taskfile.yml b/Taskfile.yml index c4320bd..581f11c 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -2,21 +2,29 @@ version: "3" tasks: format: desc: formats all lua files in repo - cmds: [stylua .] + cmds: + - stylua . lint: desc: runs all linters cmds: - - task: lint_selene - - task: lint_stylua + - task: selene + - task: stylua:check - lint_selene: + selene: desc: runs lua linter(selene) - cmds: [selene .] + cmds: + - selene . - lint_stylua: + stylua:check: desc: runs stylua in check mode - cmds: [stylua --check .] + cmds: + - stylua --check . + + stylua: + desc: runs lua formatter + cmds: + - stylua . test: desc: runs all tests @@ -24,7 +32,18 @@ tasks: cmds: - | nvim --headless \ - -u ./spec/minimal_init.lua\ + -u ./scripts/minimal_init.lua \ -c "PlenaryBustedDirectory spec \ - {minimal_init='./spec/minimal_init.lua'\ - ,sequential=true}" + {minimal_init='./scripts/minimal_init.lua' \ + ,sequential=true}" \ + -c ":qa!" + + docgen: + desc: generate vimhelp + cmds: + - | + nvim --noplugin \ + --headless \ + -u "./scripts/minimal_init.lua" \ + -c "luafile ./scripts/docgen.lua" \ + -c ":qa!" diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..61ffc7c --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +/tags diff --git a/doc/gopher.nvim.txt b/doc/gopher.nvim.txt new file mode 100644 index 0000000..7118e3c --- /dev/null +++ b/doc/gopher.nvim.txt @@ -0,0 +1,220 @@ +*gopher.nvim* + +============================================================================== + +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| + Modifty struct tags................................|gopher.nvim-struct-tags| + Auto implementation of interface methods..................|gopher.nvim-impl| + Generating unit tests boilerplate......................|gopher.nvim-gotests| + Iferr....................................................|gopher.nvim-iferr| + Generate comments.....................................|gopher.nvim-comments| + Setup `nvim-dap` for Go......................................|gopher.nvim-dap| + +------------------------------------------------------------------------------ + *gopher.nvim-setup* + `gopher.setup` +Setup function. This method simply merges default configs with opts table. +You can read more about configuration at |gopher.nvim-config| +Calling this function is optional, if you ok with default settings. Look |gopher.nvim.config-defaults| + +Usage ~ +`require("gopher").setup {}` (replace `{}` with your `config` table) + +------------------------------------------------------------------------------ + *gopher.nvim-install-deps* + `gopher.install_deps` +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 ues lua api. + + +============================================================================== +------------------------------------------------------------------------------ + *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 + + -- user specified paths to binaries + ---@class gopher.ConfigCommand + commands = { + go = "go", + gomodifytags = "gomodifytags", + gotests = "gotests", + impl = "impl", + iferr = "iferr", + dlv = "dlv", + }, + ---@class gopher.ConfigGotests + gotests = { + -- gotests doesn't have template named "default" so this plugin uses "default" to set the default template + template = "default", + -- path to a directory containing custom test code templates + ---@type string|nil + template_dir = nil, + -- switch table tests from using slice to map (with test name for the key) + -- works only with gotests installed from develop branch + named = false, + }, + ---@class gopher.ConfigGoTag + gotag = { + ---@type gopher.ConfigGoTagTransform + transform = "snakecase", + }, + } +< +Class ~ +{gopher.Config} + +------------------------------------------------------------------------------ + *config.setup()* + `config.setup`({user_config}) +Parameters ~ +{user_config} `(optional)` gopher.Config + + +============================================================================== +------------------------------------------------------------------------------ + *gopher.nvim-struct-tags* +struct-tags is utilizing the `gomodifytags` tool to add or remove tags to struct fields. +Usage ~ +- put your coursor on the struct +- run `:GoTagAdd json` to add json tags to struct fields +- run `:GoTagRm json` to remove json tags to struct fields + +note: if you dont spesify the tag it will use `json` as default + +simple example: +>go + // before + type User struct { + // ^ put your cursor here + // run `:GoTagAdd yaml` + ID int + Name string + } + + // after + type User struct { + ID int `yaml:id` + Name string `yaml:name` + } +< + + +============================================================================== +------------------------------------------------------------------------------ + *gopher.nvim-impl* +impl is utilizing the `impl` tool to generate method stubs for interfaces. +Usage ~ + +1. put your coursor on the struct on which you want implement the interface + and run `:GoImpl io.Reader` + which will automatically choose the reciver for the methods and + implement the `io.Reader` interface +2. same as previous but with custom receiver, so put your coursor on the struct + run `:GoImpl w io.Writer` + where `w` is the receiver and `io.Writer` is the interface +3. specift receiver, struct, and interface + there's no need to put your coursor on the struct if you specify all arguments + `:GoImpl r RequestReader io.Reader` + where `r` is the receiver, `RequestReader` is the struct and `io.Reader` is the interface + +simple example: +>go + type BytesReader struct{} + // ^ put your cursor here + // run `:GoImpl b io.Reader` + + // this is what you will get + func (b *BytesReader) Read(p []byte) (n int, err error) { + panic("not implemented") // TODO: Implement + } +< + + +============================================================================== +------------------------------------------------------------------------------ + *gopher.nvim-gotests* +gotests is utilizing the `gotests` tool to generate unit tests boilerplate. +Usage ~ + +- generate unit test for spesisfic function/method + - to specift the function/method put your cursor on it + - run `:GoTestAdd` + +- generate unit tests for all functions/methods in current file + - run `:GoTestsAll` + +- generate unit tests only for exported(public) functions/methods + - run `:GoTestsExp` + +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* + +if you prefare using named tests, you can enable it in the config. +but you would need to install `gotests@develop` because stable version doesn't support this feature. +you can do it with: +>lua + -- simply run go get in your shell: + go install github.com/cweill/gotests/...@develop + + -- if you want to install it within neovim, you can use one of this: + + vim.fn.jobstart("go install github.com/cweill/gotests/...@develop") + + -- or if you want to use mason: + require("mason-tool-installer").setup { + ensure_installed = { + { "gotests", version = "develop" }, + } + } +< + +if you choose to install `gotests` within neovim, i recommend adding it to your `build` section in your |lazy.nvim| + + +============================================================================== +------------------------------------------------------------------------------ + *gopher.nvim-iferr* +if you're using `iferr` tool, this module provides a way to automatically insert `if err != nil` check. +Usage ~ +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. + + +============================================================================== +------------------------------------------------------------------------------ + *gopher.nvim-dap* +This module sets up `nvim-dap` for Go. +Usage ~ +just call `require("gopher.dap").setup()`, and you're good to go. + + + vim:tw=78:ts=8:noet:ft=help:norl: \ No newline at end of file diff --git a/lua/gopher/comment.lua b/lua/gopher/comment.lua index 0a146fb..002894c 100644 --- a/lua/gopher/comment.lua +++ b/lua/gopher/comment.lua @@ -1,3 +1,8 @@ +---@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. + local function generate(row, col) local ts_utils = require "gopher._utils.ts" local comment, ns = nil, nil diff --git a/lua/gopher/config.lua b/lua/gopher/config.lua index fca13a7..c0a0dcc 100644 --- a/lua/gopher/config.lua +++ b/lua/gopher/config.lua @@ -1,6 +1,17 @@ +---@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 ---@alias gopher.ConfigGoTagTransform ---| "snakecase" "GopherUser" -> "gopher_user" ---| "camelcase" "GopherUser" -> "gopherUser" @@ -9,8 +20,16 @@ local config = {} ---| "titlecase" "GopherUser" -> "Gopher User" ---| "keep" keeps the original field name +--minidoc_replace_start { + +---@tag gopher.nvim-config-defaults +---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section):gsub(">", ">lua") +--- ---@class gopher.Config local default_config = { + --minidoc_replace_end + + -- user specified paths to binaries ---@class gopher.ConfigCommand commands = { go = "go", @@ -29,7 +48,6 @@ local default_config = { template_dir = nil, -- switch table tests from using slice to map (with test name for the key) -- works only with gotests installed from develop branch - ---@type boolean named = false, }, ---@class gopher.ConfigGoTag @@ -38,8 +56,10 @@ local default_config = { transform = "snakecase", }, } +--minidoc_afterlines_end ---@type gopher.Config +---@private local _config = default_config ---@param user_config? gopher.Config diff --git a/lua/gopher/dap.lua b/lua/gopher/dap.lua index 551416c..6ff326a 100644 --- a/lua/gopher/dap.lua +++ b/lua/gopher/dap.lua @@ -1,3 +1,8 @@ +---@toc_entry Setup `nvim-dap` for Go +---@tag gopher.nvim-dap +---@text This module sets up `nvim-dap` for Go. +---@usage just call `require("gopher.dap").setup()`, and you're good to go. + local u = require "gopher._utils" local c = require "gopher.config" local dap = {} @@ -106,7 +111,7 @@ dap.configuration = { }, } ----setup `nvim-dap` for Go +-- sets ups nvim-dap for Go in one function call. function dap.setup() local d = u.sreq "dap" diff --git a/lua/gopher/gotests.lua b/lua/gopher/gotests.lua index 0ef52cc..3d96a05 100644 --- a/lua/gopher/gotests.lua +++ b/lua/gopher/gotests.lua @@ -1,3 +1,44 @@ +---@toc_entry Generating unit tests boilerplate +---@tag gopher.nvim-gotests +---@text gotests is utilizing the `gotests` tool to generate unit tests boilerplate. +---@usage +--- - generate unit test for spesisfic function/method +--- - to specift the function/method put your cursor on it +--- - run `:GoTestAdd` +--- +--- - generate unit tests for all functions/methods in current file +--- - run `:GoTestsAll` +--- +--- - generate unit tests only for exported(public) functions/methods +--- - run `:GoTestsExp` +--- +--- 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 +--- if you prefare using named tests, you can enable it in the config. +--- but you would need to install `gotests@develop` because stable version doesn't support this feature. +--- you can do it with: +--- >lua +--- -- simply run go get in your shell: +--- go install github.com/cweill/gotests/...@develop +--- +--- -- if you want to install it within neovim, you can use one of this: +--- +--- vim.fn.jobstart("go install github.com/cweill/gotests/...@develop") +--- +--- -- or if you want to use mason: +--- require("mason-tool-installer").setup { +--- ensure_installed = { +--- { "gotests", version = "develop" }, +--- } +--- } +--- < +--- +--- if you choose to install `gotests` within neovim, i recommend adding it to your `build` section in your |lazy.nvim| + local c = require "gopher.config" local ts_utils = require "gopher._utils.ts" local r = require "gopher._utils.runner" @@ -5,6 +46,7 @@ local u = require "gopher._utils" local gotests = {} ---@param args table +---@private local function add_test(args) if c.gotests.named then table.insert(args, "-named") @@ -35,7 +77,7 @@ local function add_test(args) }) end ----generate unit test for one function +-- generate unit test for one function function gotests.func_test() local ns = ts_utils.get_func_method_node_at_pos(unpack(vim.api.nvim_win_get_cursor(0))) if ns == nil or ns.name == nil then @@ -46,12 +88,12 @@ function gotests.func_test() add_test { "-only", ns.name } end ----generate unit tests for all functions in current file +-- generate unit tests for all functions in current file function gotests.all_tests() add_test { "-all" } end ----generate unit tests for all exported functions +-- generate unit tests for all exported functions function gotests.all_exported_tests() add_test { "-exported" } end diff --git a/lua/gopher/iferr.lua b/lua/gopher/iferr.lua index 1eac0ce..56e9644 100644 --- a/lua/gopher/iferr.lua +++ b/lua/gopher/iferr.lua @@ -1,7 +1,12 @@ +---@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. +---@usage execute `:GoIfErr` near any err variable to insert the check + local c = require "gopher.config" local iferr = {} --- That's Lua of vimscript implementation of: github.com/koron/iferr +-- That's Lua implementation: github.com/koron/iferr function iferr.iferr() local boff = vim.fn.wordcount().cursor_bytes local pos = vim.fn.getcurpos()[2] diff --git a/lua/gopher/impl.lua b/lua/gopher/impl.lua index 155d6c2..f461376 100644 --- a/lua/gopher/impl.lua +++ b/lua/gopher/impl.lua @@ -1,3 +1,31 @@ +---@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. put your coursor on the struct on which you want implement the interface +--- and run `:GoImpl io.Reader` +--- which will automatically choose the reciver for the methods and +--- implement the `io.Reader` interface +--- 2. same as previous but with custom receiver, so put your coursor on the struct +--- run `:GoImpl w io.Writer` +--- where `w` is the receiver and `io.Writer` is the interface +--- 3. specift receiver, struct, and interface +--- there's no need to put your coursor on the struct if you specify all arguments +--- `:GoImpl r RequestReader io.Reader` +--- where `r` is the receiver, `RequestReader` is the struct and `io.Reader` is the interface +--- +--- simple example: +--- >go +--- type BytesReader struct{} +--- // ^ put your cursor here +--- // run `:GoImpl b io.Reader` +--- +--- // this is what you will get +--- func (b *BytesReader) Read(p []byte) (n int, err error) { +--- panic("not implemented") // TODO: Implement +--- } +--- < + local c = require("gopher.config").commands local r = require "gopher._utils.runner" local ts_utils = require "gopher._utils.ts" @@ -5,6 +33,7 @@ local u = require "gopher._utils" local impl = {} ---@return string +---@private local function get_struct() local ns = ts_utils.get_struct_node_at_pos(unpack(vim.api.nvim_win_get_cursor(0))) if ns == nil then diff --git a/lua/gopher/init.lua b/lua/gopher/init.lua index fe86577..df0d174 100644 --- a/lua/gopher/init.lua +++ b/lua/gopher/init.lua @@ -1,10 +1,35 @@ +--- *gopher.nvim* +--- +--- ============================================================================== +--- +--- 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 tags = require "gopher.struct_tags" local tests = require "gopher.gotests" local gocmd = require("gopher._utils.runner.gocmd").run local gopher = {} +---@toc_entry Setup +---@tag gopher.nvim-setup +---@text Setup function. This method simply merges default configs with opts table. +--- You can read more about configuration at |gopher.nvim-config| +--- Calling this function is optional, if you ok with default settings. Look |gopher.nvim.config-defaults| +--- +---@usage `require("gopher").setup {}` (replace `{}` with your `config` table) gopher.setup = require("gopher.config").setup + +---@toc_entry Install dependencies +---@tag gopher.nvim-install-deps +---@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 ues lua api. gopher.install_deps = require("gopher.installer").install_deps + gopher.impl = require("gopher.impl").impl gopher.iferr = require("gopher.iferr").iferr gopher.comment = require "gopher.comment" diff --git a/lua/gopher/struct_tags.lua b/lua/gopher/struct_tags.lua index afd4f87..4389b62 100644 --- a/lua/gopher/struct_tags.lua +++ b/lua/gopher/struct_tags.lua @@ -1,3 +1,29 @@ +---@toc_entry Modifty struct tags +---@tag gopher.nvim-struct-tags +---@text struct-tags is utilizing the `gomodifytags` tool to add or remove tags to struct fields. +---@usage - put your coursor on the struct +--- - run `:GoTagAdd json` to add json tags to struct fields +--- - run `:GoTagRm json` to remove json tags to struct fields +--- +--- note: if you dont spesify the tag it will use `json` as default +--- +--- simple example: +--- >go +--- // before +--- type User struct { +--- // ^ put your cursor here +--- // run `:GoTagAdd yaml` +--- ID int +--- Name string +--- } +--- +--- // after +--- type User struct { +--- ID int `yaml:id` +--- Name string `yaml:name` +--- } +--- < + local ts_utils = require "gopher._utils.ts" local r = require "gopher._utils.runner" local c = require "gopher.config" @@ -56,7 +82,7 @@ local function modify(...) or tagged["start"] == nil or tagged["start"] == 0 then - error("failed to set tags " .. vim.inspec(tagged)) + error("failed to set tags " .. vim.inspect(tagged)) end vim.api.nvim_buf_set_lines( @@ -69,8 +95,7 @@ local function modify(...) vim.cmd "write" end ----add tags to struct under cursor ----@param ... unknown +-- add tags to struct under cursor function struct_tags.add(...) local arg = { ... } if #arg == nil or arg == "" then @@ -85,8 +110,7 @@ function struct_tags.add(...) modify(unpack(cmd_args)) end ----remove tags to struct under cursor ----@param ... unknown +-- remove tags to struct under cursor function struct_tags.remove(...) local arg = { ... } if #arg == nil or arg == "" then diff --git a/scripts/docgen.lua b/scripts/docgen.lua new file mode 100644 index 0000000..f2deb8b --- /dev/null +++ b/scripts/docgen.lua @@ -0,0 +1,33 @@ +---@diagnostic disable: undefined-global +--# selene: allow(undefined_variable) + +local okay, minidoc = pcall(require, "mini.doc") +if not okay then + error "mini.doc not found, please install it. https://github.com/echasnovski/mini.doc" + return +end + +local files = { + "lua/gopher/init.lua", + "lua/gopher/config.lua", + "lua/gopher/struct_tags.lua", + "lua/gopher/impl.lua", + "lua/gopher/gotests.lua", + "lua/gopher/iferr.lua", + "lua/gopher/comment.lua", + "lua/gopher/dap.lua", +} + +minidoc.setup() + +local hooks = vim.deepcopy(minidoc.default_hooks) +hooks.write_pre = function(lines) + -- Remove first two lines with `======` and `------` delimiters to comply + -- with `:h local-additions` template + table.remove(lines, 1) + table.remove(lines, 1) + + return lines +end + +MiniDoc.generate(files, "doc/gopher.nvim.txt", { hooks = hooks }) diff --git a/spec/minimal_init.lua b/scripts/minimal_init.lua similarity index 93% rename from spec/minimal_init.lua rename to scripts/minimal_init.lua index 163efc5..49a606e 100644 --- a/spec/minimal_init.lua +++ b/scripts/minimal_init.lua @@ -26,6 +26,7 @@ vim.notify = print install_plug "nvim-lua/plenary.nvim" install_plug "nvim-treesitter/nvim-treesitter" +install_plug "echasnovski/mini.doc" -- used for docs generation vim.env.XDG_CONFIG_HOME = root ".tests/config" vim.env.XDG_DATA_HOME = root ".tests/data"