Comment.nvim 实现代码块行尾注释的高效方案

在编写技术文档时，我们经常需要在代码块中添加特殊标记来突出显示某些行。本文介绍如何利用Comment.nvim插件实现智能化的行尾注释功能，特别适用于Vitepress等文档工具中的代码高亮需求。

核心需求分析

现代文档工具如Vitepress提供了代码行高亮功能，通过在行尾添加特定注释来实现。例如：

const msg = 'Hello'; // [!code highlight]

不同编程语言的注释符号各不相同，我们需要一个能根据代码块语言自动选择正确注释符号的解决方案。

实现方案详解

1. 获取当前代码块语言

首先需要确定当前代码块使用的编程语言：

local function get_lang()
  local curline = vim.fn.line('.')
  local lang = vim.treesitter.get_parser():language_for_range({ curline, 0, curline, 0 }):lang()
  return lang
end

这段代码利用Neovim的treesitter API获取当前行的语言上下文。

2. 获取语言对应的注释符号

通过Comment.nvim提供的接口获取特定语言的注释格式：

local function get_ctx()
  local lang = get_lang()
  assert(lang, 'lang not found')
  local cs = require('Comment.ft').get(lang)
  assert(cs, 'comment string not found')
  return cs, lang
end

3. 动态修改注释格式并添加行尾注释

核心功能是临时修改注释格式，添加特定后缀后恢复原设置：

local function comment_eol(suffix)
  return function()
    local success, cs, lang = pcall(get_ctx)
    if not success then return end
    
    local ori_cs = type(cs) == 'string' and cs or cs[1]
    local pos = ori_cs:find('%%s')
    local sub = pos and ori_cs:sub(1, pos - 1) .. ' ' .. suffix .. ori_cs:sub(pos) 
               or ori_cs .. suffix
    
    require('Comment.ft').set(lang, sub)
    require('Comment.api').insert.linewise.eol()
    require('Comment.ft').set(lang, cs)
  end
end

4. 为多行选择添加注释

处理可视模式下的多行选择：

local function foreach_line(action)
  return function()
    local start_line = vim.fn.line('v')
    local end_line = vim.fn.line('.')
    vim.api.nvim_feedkeys(vim.api.nvim_replace_termcodes('<ESC>', true, false, true), 'x', false)
    for i = math.min(start_line, end_line), math.max(start_line, end_line) do
      vim.cmd(tostring(i))
      action()
    end
  end
end

实际应用示例

配置快捷键映射，支持多种注释类型：

-- 单行操作
vim.keymap.set('n', 'gva', comment_eol('[!code ++]'))
vim.keymap.set('n', 'gvd', comment_eol('[!code --]'))

-- 多行操作
vim.keymap.set('x', 'vva', foreach_line(comment_eol('[!code ++]')))
vim.keymap.set('x', 'vvd', foreach_line(comment_eol('[!code --]')))

技术要点总结

1. 上下文感知：自动识别代码块语言，使用正确的注释符号
2. 临时修改配置：动态调整Comment.nvim的注释格式，操作后恢复原设置
3. 多行处理：支持可视模式下的批量操作
4. 可扩展性：轻松添加新的注释类型和快捷键

这个方案不仅解决了Vitepress文档中的代码高亮需求，其设计思路也可应用于其他需要智能注释的场景，展示了Neovim插件开发的灵活性和强大功能。