tree-sitter-jsdoc: Rust语法树解析库使用指南

介绍

tree-sitter-jsdoc 是一个基于 tree-sitter 的 Rust 库，专门用于解析 JavaScript 文档注释（JSDoc）。它能够高效地从 JavaScript 代码中提取和解析 JSDoc 注释，并将其转换为结构化的数据，便于进一步处理和分析。

主要特性

• 高性能的 JSDoc 注释解析
• 准确的语法树构建
• 支持大多数常见的 JSDoc 标签
• 易于集成的 Rust API

安装

在 Cargo.toml 中添加依赖：

[dependencies]
tree-sitter-jsdoc = "0.20"
tree-sitter = "0.20"

基本使用方法

1. 解析单个 JSDoc 注释

use tree_sitter_jsdoc::parse_jsdoc;

fn main() {
    let jsdoc_comment = r#"
    /**
     * Calculates the sum of two numbers
     * @param {number} a - first number
     * @param {number} b - second number
     * @returns {number} sum of a and b
     */
    "#;

    let parsed = parse_jsdoc(jsdoc_comment).unwrap();
    println!("{:#?}", parsed);
}

2. 从 JavaScript 文件中提取 JSDoc

use tree_sitter::{Parser, Tree};
use tree_sitter_jsdoc::extract_jsdoc_comments;

fn main() {
    let js_code = r#"
    /**
     * @module math
     */
    
    /**
     * Adds two numbers
     * @param {number} x 
     * @param {number} y
     * @returns {number}
     */
    function add(x, y) {
        return x + y;
    }
    "#;

    let mut parser = Parser::new();
    parser.set_language(tree_sitter_javascript::language()).unwrap();
    let tree = parser.parse(js_code, None).unwrap();
    
    let jsdocs = extract_jsdoc_comments(&tree, js_code);
    for jsdoc in jsdocs {
        println!("Found JSDoc:\n{}", jsdoc.text);
        let parsed = parse_jsdoc(&jsdoc.text).unwrap();
        println!("Parsed: {:#?}", parsed);
    }
}

完整示例代码

下面是一个完整的示例，展示如何使用 tree-sitter-jsdoc 从 JavaScript 文件中提取 JSDoc 注释并生成文档摘要：

use tree_sitter::{Parser, Tree};
use tree_sitter_jsdoc::{extract_jsdoc_comments, parse_jsdoc, JsDocTag};

fn main() {
    // 示例 JavaScript 代码包含多个 JSDoc 注释
    let js_code = r#"
    /**
     * @module math/operations
     * @description Math operations library
     */
    
    /**
     * Adds two numbers
     * @param {number} x - The first number
     * @param {number} y - The second number
     * @returns {number} The sum of x and y
     * @example
     * add(2, 3) // returns 5
     */
    function add(x, y) {
        return x + y;
    }
    
    /**
     * Multiplies two numbers
     * @param {number} a - First factor
     * @param {number} b - Second factor
     * @returns {number} The product of a and b
     * @custom This is a custom tag
     */
    function multiply(a, b) {
        return a * b;
    }
    "#;

    // 1. 初始化 tree-sitter 解析器
    let mut parser = Parser::new();
    parser.set_language(tree_sitter_javascript::language()).unwrap();
    
    // 2. 解析 JavaScript 代码
    let tree = parser.parse(js_code, None).unwrap();
    
    // 3. 提取所有 JSDoc 注释
    let jsdocs = extract_jsdoc_comments(&tree, js_code);
    
    // 4. 处理每个 JSDoc 注释
    for (i, jsdoc) in jsdocs.iter().enumerate() {
        println!("\n=== JSDoc {} ===", i + 1);
        
        // 4.1 打印原始 JSDoc 文本
        println!("Raw JSDoc:\n{}", jsdoc.text);
        
        // 4.2 解析 JSDoc
        match parse_jsdoc(&jsdoc.text) {
            Ok(parsed) => {
                // 4.3 生成并打印摘要
                let summary = generate_summary(&parsed);
                println!("\nGenerated Summary:\n{}", summary);
                
                // 4.4 处理自定义标签
                handle_custom_tags(&parsed);
            }
            Err(e) => {
                eprintln!("Failed to parse JSDoc: {}", e);
            }
        }
    }
}

/// 生成 JSDoc 注释的文本摘要
fn generate_summary(parsed: &tree_sitter_jsdoc::JsDoc) -> String {
    let mut summary = String::new();
    
    // 添加描述
    if let Some(desc) = &parsed.description {
        summary.push_str(&format!("Description: {}\n", desc));
    }
    
    // 处理所有标签
    for tag in &parsed.tags {
        match tag {
            JsDocTag::Param(param) => {
                summary.push_str(&format!(
                    "Parameter: {} ({}): {}\n", 
                    param.name, 
                    param.type_name.as_deref().unwrap_or("unknown"),
                    param.description.as_deref().unwrap_or("")
                ));
            }
            JsDocTag::Returns(ret) => {
                summary.push_str(&format!(
                    "Returns: {}: {}\n",
                    ret.type_name.as_deref().unwrap_or("unknown"),
                    ret.description.as_deref().unwrap_or("")
                ));
            }
            JsDocTag::Module(module) => {
                summary.push_str(&format!("Module: {}\n", module.name));
            }
            JsDocTag::Description(desc) => {
                summary.push_str(&format!("Description: {}\n", desc.text));
            }
            JsDocTag::Example(example) => {
                summary.push_str(&format!("Example: {}\n", example.text));
            }
            _ => {}
        }
    }
    
    summary
}

/// 处理自定义标签
fn handle_custom_tags(parsed: &tree_sitter_jsdoc::JsDoc) {
    for tag in &parsed.tags {
        if let JsDocTag::Unknown(tag_name, content) = tag {
            println!("Found custom tag @{}: {}", tag_name, content.as_deref().unwrap_or(""));
        }
    }
}

示例输出

运行上述代码将输出类似以下内容：

=== JSDoc 1 ===
Raw JSDoc:
/**
     * @module math/operations
     * @description Math operations library
     */

Generated Summary:
Module: math/operations
Description: Math operations library

=== JSDoc 2 ===
Raw JSDoc:
/**
     * Adds two numbers
     * @param {number} x - The first number
     * @param {number} y - The second number
     * @returns {number} The sum of x and y
     * @example
     * add(2, 3) // returns 5
     */

Generated Summary:
Description: Adds two numbers
Parameter: x (number): The first number
Parameter: y (number): The second number
Returns: number: The sum of x and y
Example: 
     * add(2, 3) // returns 5

=== JSDoc 3 ===
Raw JSDoc:
/**
     * Multiplies two numbers
     * @param {number} a - First factor
     * @param {number} b - Second factor
     * @returns {number} The product of a and b
     * @custom This is a custom tag
     */

Generated Summary:
Description: Multiplies two numbers
Parameter: a (number): First factor
Parameter: b (number): Second factor
Returns: number: The product of a and b

Found custom tag @custom: This is a custom tag