Documentation on Neovim/Vim is incomplete

Techatrix commented 3 months ago

Related Issue for Emacs: zigtools/www.zigtools.org#1

Installation Guide

[ ] inform the reader about ziglang/zig.vim because they may unknowingly use it. As an example, the user may wonder why formatting on save is enabled or what is causing https://github.com/zigtools/zls/issues/856

nvim-lspconfig

This documentation mostly complete and should be taken as a reference for the other plugins.

[ ] document how to use lazy-vim instead of vim-plug. See nvim-lspconfig docs from lazy-vim

Conquer of Completion (CoC)

[x] Figure out what to do about the coc-zls plugin since it appears to be unmaintained.
[ ] document how to manually specify the path to Zig (if possible)
[ ] document how to set ZLS config options (if possible)

YouCompleteMe

[ ] document how to manually specify the path to Zig and ZLS
[ ] document how to set ZLS config options lsp-configuration

LanguageClient-neovim

[ ] document how to manually specify the path to Zig and ZLS
[ ] document how to set ZLS config options g:LanguageClient_settingsPath

Also, are there any other plugins that should be included?

How to view ZLS log output Guide

[ ] add guide for CoC (if possible)
[ ] add guide for YouCompleteMe (if possible)
[ ] add guide for LanguageClient-neovim (if possible)

BratishkaErik commented 3 months ago

Conquer of Completion (CoC)

Figure out what to do about the coc-zls plugin since it appears to be unmaintained. There also is coc-zig which also appears to be unmaintained. Is anyone even using CoC with Zig?

I use it with NeoVim but without any mentioned plugins. IIRC these coc-plugins are not even required if you want to use ZLS in CoC, you can just supply it manually. I also have "ziglang/zig.vim" installed, but AFAIK I don't use any feature here (auto-formatting on saving is disabled etc.). Here's part of my init.lua:

local use = require('packer').use
require('packer').startup(function()
  use 'wbthomason/packer.nvim' -- Package manager

  use 'ziglang/zig.vim'

  use { 'neoclide/coc.nvim', branch = 'release' }

  use 'folke/tokyonight.nvim'

  use {
    'nvim-lualine/lualine.nvim',
    requires = { 'kyazdani42/nvim-web-devicons', opt = true }
  }
end)

-- ...

vim.g.zig_fmt_autosave = 0

-- LSP, code completion and search
vim.opt.incsearch = true
vim.opt.signcolumn = "yes"
vim.opt.updatetime = 500

-- Use Tab for trigger completion with characters ahead and navigate
-- NOTE: Use command ':verbose imap <tab>' to make sure Tab is not mapped by
-- other plugins before putting this into your config
local opts = {
    silent = true,
    noremap = true,
    expr = true,
}

function _G.check_back_space()
    local col = vim.fn.col('.') - 1
    return col == 0 or vim.fn.getline('.'):sub(col, col):match('%s') ~= nil
end

-- Tab and Shift-TAB for moving between entries.
vim.keymap.set('i', '<TAB>', 'coc#pum#visible() ? coc#pum#next(1) : v:lua.check_back_space() ? "<TAB>" : coc#refresh()', opts)
vim.keymap.set('i', '<S-TAB>', [[coc#pum#visible() ? coc#pum#prev(1) : "\<C-h>"]], opts)
-- Make <CR> to accept selected completion item.
vim.keymap.set('i', "<cr>", [[coc#pum#visible() ? coc#pum#confirm() : "\<C-g>u\<CR>\<c-r>=coc#on_enter()\<CR>"]], opts)
-- Use `[g` and `]g` to navigate diagnostics.
-- Use `:CocDiagnostics` to get all diagnostics of current buffer in location list.
vim.keymap.set('n', '[g', '<Plug>(coc-diagnostic-prev)', { silent = true })
vim.keymap.set('n', ']g', '<Plug>(coc-diagnostic-next)', { silent = true })
-- GoTo code navigation.
vim.keymap.set('n', 'gd', '<Plug>(coc-definition)', { silent = true })

-- ...

And my coc-settings.json:

{
    "coc.preferences.formatOnSave": false,
    "suggest.noselect": true,

    "languageserver": {
        "zls" : {
            "command": "zls",
            "filetypes": ["zig"]
        },
        "clangd": {
            "command": "clangd",
            "rootPatterns": ["compile_flags.txt", "compile_commands.json"],
            "filetypes": ["c", "cc", "cpp", "c++", "objc", "objcpp"]
        },
        "golang": {
            "command": "gopls",
            "rootPatterns": ["go.mod"],
            "filetypes": ["go"]
        },
        "rust": {
            "command": "rust-analyzer",
            "rootPatterns": ["Cargo.toml"],
            "filetypes": ["rust"]
        }
    }
}

Working nice so far. I think you can omit links to that plugins and leave only manual method (https://github.com/zigtools/zls/wiki/Installation/ca8a7f700fdc83f81353a351581898df9849a4ff#manually):

{
    "languageserver": {
        "zls" : {
            "command": "zls",
            "filetypes": ["zig"]
        }
    }
}

(Do you plan to support ZON btw?)

Techatrix commented 3 months ago

Even though CoC is usable without any addition plugin, they can still provide some advantages. Since coc-zls copies vscode-zig, it can provide all the features you find in vscode-zig. Most notably the ability to install Zig and ZLS for you.

After taking closer look at the code, I realize that the ZLS install doesn't work anymore. All other features in coc-zls are already provided by ZLS like build on save, ast-check, formatting. It makes sense to have them in vscode-zig since ZLS is an optional part of it but not for CoC.

Doesn't seem like there is good reason to include coc-zls when considering all the potential issues it could cause. I will remove it from the Installation Guide.

(Do you plan to support ZON btw?)

ZLS should already support .zon files. Well, "support" in the sense that it can provide semantic highlighting but nothing else (yet). I don't know whether this applies to CoC. It is possible that ziglang/zig.vim is being used for syntax highlighting instead of ZLS.

BratishkaErik commented 3 months ago

ZLS should already support .zon files. Well, "support" in the sense that it can provide semantic highlighting but nothing else (yet). I don't know whether this applies to CoC. It is possible that ziglang/zig.vim is being used for syntax highlighting instead of ZLS.

I have tested it today, and with small tweaks I can now see synatx highlighting from ZLS in both .zig and .zon files:

{
    "coc.preferences.formatOnSave": false,
    "semanticTokens.enable": true,
    "suggest.noselect": true,

    "languageserver": {
        "zls" : {
            "command": "zls",
            "filetypes": ["zig", "zon"]
        },
        "clangd": {
            "command": "clangd",
            "rootPatterns": ["compile_flags.txt", "compile_commands.json"],
            "filetypes": ["c", "cc", "cpp", "c++", "objc", "objcpp"]
        },
        "golang": {
            "command": "gopls",
            "rootPatterns": ["go.mod"],
            "filetypes": ["go"]
        },
        "rust": {
            "command": "rust-analyzer",
            "rootPatterns": ["Cargo.toml"],
            "filetypes": ["rust"]
        }
    }
}

I think it makes sense then to also add "zon" extensions to the example CoC config in wiki:

{
    "languageserver": {
        "zls" : {
            "command": "zls",
            "filetypes": [ "zig", "zon" ]
        }
    }
}

Techatrix commented 3 months ago

I think it makes sense then to also add "zon" extensions to the example CoC config in wiki:

And what about "semanticTokens.enable": true,? Shouldn't that also be added (or at least be mentioned)?

BratishkaErik commented 3 months ago

During tweaking I had also found out that neovim nowadays bundles Zig syntax support which is copied from upstream zig.vim extension, and this bundled highlighting is what I used before tweaking, unknowingly. Here's it for comparison:

/usr/share/nvim/runtime/syntax/zig.vim:

" Vim syntax file " Language: Zig " Upstream: https://github.com/ziglang/zig.vim

BratishkaErik commented 3 months ago

And what about "semanticTokens.enable": true,? Shouldn't that also be added (or at least be mentioned)?

I was going to write about this in previous message too, but when I almost finished it I saw your message and cut that part (context is 3 previous messages).

Cutted part:

I think we should also mention "semanticTokens.enable" option, it is for enabling use of syntax highlighting support from LSP, but it's disabled by default by coc.nvim because it's considered a little bit experimental. But, as I mentioned in this message in upper part, neovim also bundles syntax highlight from ziglang.nvim, perhaps we should mention it too in beginning of NeoVim section, maybe under name "basic, default syntax highlighting (no plugins)"?

Techatrix commented 3 months ago

I noticed that in the image with semantic tokens enabled, the inlay hints are colored green. This looks a bit unusual to me since types are also highlighted in green.

When mentioning the "semanticTokens.enable" option, I think that inlayHint.enable should also be mentioned. Not because the default should be changed but to inform the user about inlay hints.

ziglang.nvim, perhaps we should mention it too in beginning of NeoVim section, maybe under name "basic, default syntax highlighting (no plugins)"?

This ties into the first task of the Issue: "inform the reader about ziglang/zig.vim". CoC is not the only case where ziglang/zig.vim can be used for syntax highlighting.

Here is what I could imagine for the coc-settings.json:

{
    // Show inlay hints in the editor. Inlay hints are short annotations within the code,
    // which show variable types or parameter names.
    "inlayHint.enable": true,
    "semanticTokens.enable": true,

    "languageserver": {
        "zls" : {
            "command": "zls",
            "filetypes": [ "zig", "zon" ]
        }
    }
}

I will still have to take a look at how to document format on save since both ziglang/zig.vim and CoC provide it.

BratishkaErik commented 3 months ago

Seems reasonable, thanks!

zigtools / www.zigtools.org