如何在自定义VSCode语言扩展中实现悬停显示函数定义？

核心思路 #

悬停显示函数定义本质是通过**语言服务（Language Service）**解析当前文档，定位到函数的定义节点，提取函数签名、参数、注释等信息后返回给VSCode的悬停提供者。

具体实现步骤 #

1. 先搞定语法解析（关键前提） #

要识别函数定义，首先得有对应的语法分析能力：

• 如果用vscode-languageserver框架，需要在语法文件（比如.tmLanguage.json或lezer parser规则）里定义函数结构的匹配规则，确保能正确识别函数名、参数列表、返回值等核心部分。
• 若语法简单，也可以自己实现简易AST解析，遍历文档文本定位函数定义的位置和关键信息。

2. 扩展Hover Provider逻辑 #

在扩展激活代码里，给已注册的Hover Provider新增函数定义处理逻辑：

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    const hoverProvider = vscode.languages.registerHoverProvider('你的自定义语言ID', {
        async provideHover(document: vscode.TextDocument, position: vscode.Position) {
            const range = document.getWordRangeAtPosition(position);
            if (!range) return undefined;
            
            const targetName = document.getText(range);
            // 保留你已实现的定义位置跳转逻辑
            // ...（你的现有代码）

            // 新增函数定义提取逻辑
            const funcDef = await getFunctionDefinition(document, targetName);
            if (funcDef) {
                const hoverContent = new vscode.MarkdownString();
                // 拼接函数签名的代码块
                hoverContent.appendCodeblock(
                    `function ${funcDef.name}(${funcDef.params.join(', ')})${funcDef.returnType ? `: ${funcDef.returnType}` : ''}`,
                    '你的自定义语言ID'
                );
                // 追加注释（如果有）
                if (funcDef.comment) {
                    hoverContent.appendMarkdown(`\n\n${funcDef.comment}`);
                }
                return new vscode.Hover(hoverContent);
            }

            return undefined;
        }
    });

    context.subscriptions.push(hoverProvider);
}

// 示例：查找函数定义的辅助函数（根据你的语言语法调整）
async function getFunctionDefinition(doc: vscode.TextDocument, funcName: string) {
    const fullText = doc.getText();
    // 假设你的语言函数定义格式是：func 函数名(参数1:类型, 参数2:类型): 返回类型 { ... }
    const regex = new RegExp(`func\\s+${funcName}\\s*\\((.*?)\\)(?:\\s*:\\s*(\\w+))?`, 'gs');
    let matchResult;
    
    while ((matchResult = regex.exec(fullText)) !== null) {
        const params = matchResult[1] ? matchResult[1].split(',').map(p => p.trim()) : [];
        const returnType = matchResult[2];
        
        // 可选：提取函数上方的单行注释
        const commentStartPos = regex.lastIndex - matchResult[0].length - 1;
        const commentRange = new vscode.Range(
            doc.positionAt(commentStartPos),
            doc.positionAt(regex.lastIndex - matchResult[0].length)
        );
        const comment = doc.getText(commentRange).trim().startsWith('//') ? doc.getText(commentRange).trim() : undefined;

        return {
            name: funcName,
            params,
            returnType,
            comment
        };
    }
    return undefined;
}

3. 关于JSON文件方案的说明 #

用JSON维护函数元数据是轻量方案，适合内置函数少、语法简单的场景：

• 提前把内置函数的信息存在functionDocs.json里：

  {
    "calculateSum": {
      "params": ["a: number", "b: number"],
      "returnType": "number",
      "comment": "计算两个数字的和，返回结果"
    }
  }
  

• 在Hover Provider里直接读取JSON匹配返回：

  import * as fs from 'fs';
  import * as path from 'path';
  
  const funcDocs = JSON.parse(fs.readFileSync(path.join(__dirname, 'functionDocs.json'), 'utf8'));
  
  // 在provideHover逻辑中：
  if (funcDocs[targetName]) {
      const doc = funcDocs[targetName];
      const hoverContent = new vscode.MarkdownString();
      hoverContent.appendCodeblock(`function ${targetName}(${doc.params.join(', ')})${doc.returnType ? `: ${doc.returnType}` : ''}`, '你的自定义语言ID');
      hoverContent.appendMarkdown(`\n\n${doc.comment}`);
      return new vscode.Hover(hoverContent);
  }
  

这种方案不用复杂解析，但仅支持静态内置函数，无法处理用户自定义函数。

4. 进阶方案：基于LSP框架实现 #

如果扩展功能复杂，优先用vscode-languageserver-node框架，它内置完善的语义分析能力：

• 在语言服务中实现hover方法，通过构建AST精准提取函数定义，还能和跳转、补全等功能联动。

注意事项 #

• 正则匹配适合简单场景，复杂语法下优先用AST解析避免出错。
• 处理大文件时，可限制搜索范围（比如光标上下各500行）提升性能。
• 悬停内容支持Markdown格式，合理使用代码块、换行等优化可读性。

内容的提问来源于stack exchange，提问作者wonderfuloceans