如何基于功能标志有条件地执行模块级doctest? [英] How can I conditionally execute a module-level doctest based on a feature flag?

问题描述

我正在编写一个模块的文档，该模块具有一些由Cargo功能标记控制的选项.我希望始终显示此文档，以便板条箱的使用者知道它可用，但是我只需要在启用该功能时运行该示例.

I am writing documentation for a module that has some options controlled by a Cargo feature flag. I'd like to always show this documentation so that consumers of the crate know that it's available, but I need to only run the example when the feature is enabled.

//! This crate has common utility functions
//!
//! ```
//! assert_eq!(2, featureful::add_one(1));
//! ```
//!
//! You may also want to use the feature flag `solve_halting_problem`:
//!
//! ```
//! assert!(featureful::is_p_equal_to_np());
//! ```

pub fn add_one(a: i32) -> i32 {
    a + 1
}

#[cfg(feature = "solve_halting_problem")]
pub fn is_p_equal_to_np() -> bool {
    true
}

Cargo.toml

[package]
name = "featureful"
version = "0.1.0"
authors = ["An Devloper <[e-mail]>"]

[features]
solve_halting_problem = []

[dependencies]

---

启用该功能后运行会按预期运行两个doctest:

---

Running with the feature enabled runs both doctests as expected:

$ cargo test --features=solve_halting_problem
   Doc-tests featureful

running 2 tests
test src/lib.rs -  (line 7) ... ok
test src/lib.rs -  (line 3) ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

在没有功能的情况下运行会出现错误:

Running without the feature has an error:

$ cargo test
   Doc-tests featureful

running 2 tests
test src/lib.rs -  (line 7) ... FAILED
test src/lib.rs -  (line 3) ... ok

failures:

---- src/lib.rs -  (line 7) stdout ----
    error[E0425]: cannot find function `is_p_equal_to_np` in module `featureful`
 --> src/lib.rs:8:21
  |
4 | assert!(featureful::is_p_equal_to_np());
  |                     ^^^^^^^^^^^^^^^^ not found in `featureful`

无论是否启用此功能，和 no_run 修饰符均适用，因此它们似乎没有用.

Both the ```ignore and ```no_run modifiers apply when the feature is enabled or not, so they don't seem to be useful.

一个具有doctest的Rust项目如何实现条件编译?接近，但答案集中在功能，而不是 modules 的文档中的内容.

How would one achieve conditional compilation with Rust projects that have doctests? is close, but the answer focuses on functions that change with conditional compilation, not on documentation of modules.

推荐答案

我只看到一种解决方案:将#[cfg] 放入测试中:

I only see one solution: put the #[cfg] inside the test:

//! ```
//! #[cfg(feature = "solve_halting_problem")]
//! assert!(featureful::is_p_equal_to_np());
//! ```

这将被视为测试，但是在未启用该功能时将为空.您可以将其与隐藏的功能配对示例的一部分，以及您也可以将#[cfg] 属性放在整个块上的事实:

This will count as a test but it will be empty when the feature is not enabled. You can pair this with the ability to hide portions of the example and the fact that you can put the #[cfg] attribute on entire blocks as well:

//! ```
//! # #[cfg(feature = "solve_halting_problem")] {
//! assert!(featureful::is_p_equal_to_np());
//! // Better double check
//! assert!(featureful::is_p_equal_to_np());
//! # }
//! ```

---

请注意，也许您可​​以使用

在禁用此功能时，它将不会运行测试，但是会生成带有 cargo doc --features dox 的文档.

This will not run the test when the feature is disabled but this will generate the doc with cargo doc --features dox.

这篇关于如何基于功能标志有条件地执行模块级doctest?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！