Documentation on Neovim/Vim is incomplete

[Techatrix]

Related Issue for Emacs: #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 [Neovim] LSP diagnostics go to a split zls#856

Neovim

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

• document how to use vim.pack instead of vim-plug.

Conquer of Completion (CoC)

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

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]

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]

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]

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]

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]

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]

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]

Seems reasonable, thanks!