quote-doctest

为quote提供的简单doctest和文档注释生成器

概述

目前，quote 不支持 在注释中插入文本，这意味着无法进行自定义doctests。此crate提供了一个简单的机制来生成doctests和文档注释，以便包含在生成的代码中。

[dependencies]
quote-doctest = "0.3"

示例

使用doc_test宏，我们可以将任何TokenStream转换为可以插入任何quote宏调用的doctest TokenStream。

doc_comment函数将任何字符串转换为TokenStream中的一个或多个注释。

use quote::quote;
use quote_doctest::{doc_comment, doc_test, FormatDocTest};

fn main() {
    // Takes any `TokenStream` as input (but typically `quote` would be used)
    let test = doc_test!(quote! {
        _comment_!("Calling fibonacci with 10 returns 55");
        assert_eq!(fibonacci(10), 55);
    
        _blank_!();
        _comment_!("Calling fibonacci with 1 simply returns 1");
        assert_eq!(fibonacci(1), 1);
    }).unwrap();
  
    let comment = doc_comment("This compares fib inputs and outputs:\n\n");
  
    // Interpolates into a regular `quote` invocation
    let actual = quote! {
        #comment
        #test
        fn fibonacci(n: u64) -> u64 {
            match n {
                0 => 1,
                1 => 1,
                n => fibonacci(n - 1) + fibonacci(n - 2),
            }
        }
    };
  
    // This is what is generated:
    let expected = quote! {
        /// This compares fib inputs and outputs:
        ///
        /// ```
        /// // Calling fibonacci with 10 returns 55
        /// assert_eq!(fibonacci(10), 55);
        ///
        /// // Calling fibonacci with 1 simply returns 1
        /// assert_eq!(fibonacci(1), 1);
        /// ```
        fn fibonacci(n: u64) -> u64 {
            match n {
                0 => 1,
                1 => 1,
                n => fibonacci(n - 1) + fibonacci(n - 2),
            }
        }
    };
  
    assert_eq!(expected.format_tokens().unwrap(), actual.format_tokens().unwrap());
}

注意事项

• 它利用了rust-format crate，该crate可以使用prettyplease（默认）或系统rustfmt格式化doctests。
  • 当使用rustfmt时，如果设置了RUSTFMT环境变量，则予以尊重。
• 由于注释和空行对于解析器来说是空白，因此使用标记宏来映射注释和空行应出现的位置。这些将在doctest中分别替换为注释和空行（如上例所示）。

许可证

本项目可以选择性地根据以下许可证进行授权：

• Apache许可证，版本2.0（https://apache.ac.cn/licenses/LICENSE-2.0）
• MIT许可证（https://opensource.org/licenses/MIT）