Как я могу условно выполнить doctest на уровне модуля на основе флага функции? - PullRequest
Новая
       28

Как я могу условно выполнить doctest на уровне модуля на основе флага функции?

0 голосов
/ 13 мая 2018

Я пишу документацию для модуля, который имеет некоторые опции, управляемые флагом функции Cargo. Я хотел бы всегда показывать эту документацию, чтобы потребители ящика знали, что она доступна, но мне нужно запускать пример только при включенной функции.

lib.rs 

//! 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 <an.devloper@example.com>"]

[features]
solve_halting_problem = []

[dependencies]

Запуск с включенной функцией запускает оба документа, как и ожидалось: 

$ 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

Ошибка запуска без функции: 

$ 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`

Оба модификатора ```ignore и ```no_run применяются, когда функция включена или нет, поэтому они не кажутся полезными.

Как можно добиться условной компиляции с проектами Rust, в которых есть тесты? близок, но ответ сосредоточен на функциях , которые изменяются при условной компиляции, а не на документации модули .

1 Ответ

0 голосов
/ 13 мая 2018

Я вижу только одно решение: поместите #[cfg] внутрь теста: 

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

Это будет считаться тестом, но будет пустым, когда функция не включена. Вы можете связать это со способностью скрыть части примера и с тем фактом, что вы также можете поставить атрибут #[cfg] на целые блоки: 

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

В качестве примечания, может быть, вы могли бы использовать #![feature(doc_cfg)] так: 

/// This function is super useful
///
/// ```
/// assert!(featureful::is_p_equal_to_np());
/// ```
#[cfg(any(feature = "solve_halting_problem", feature = "dox"))]
#[doc(cfg(feature = "solve_halting_problem"))]
pub fn is_p_equal_to_np() -> bool {
    true
}

Это не будет запускать тест, когда функция отключена, но это сгенерирует документ с cargo doc --features dox.

...