Есть ли какой-нибудь способ собрать документацию Rust, которая включает строки тестовой документации? - PullRequest
Новая
       101

Есть ли какой-нибудь способ собрать документацию Rust, которая включает строки тестовой документации?

0 голосов
/ 24 сентября 2019

В нашей методологии тестирования документация тестирования является первоклассным объектом при выводе документации.В частности, он определяет спецификацию, которая тестируется каждым поведенческим тестом.

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

Пример модуля будет следующим: 

/// This function does some important stuff
pub fn working_fn() -> bool {
    true
}

#[cfg(test)]
mod tests {
    //! This is some important set of tests
    //!

    use super::*;

    /// The function should work
    #[test]
    fn it_works() {
        assert!(working_fn());
    }
}

Я получаю вывод документации для общественности working_fn, но ничего для модуля tests.Я понимаю, что дополнительным осложнением является то, что тесты являются частными, и в идеале я мог бы задокументировать частные тесты, не документируя и другие частные объекты.

1 Ответ

2 голосов
/ 24 сентября 2019

Вы можете ввести новый флаг функции, который можно использовать для обработки тестов специально для целей документации.

Добавьте функцию в свой Cargo.toml: 

[features]
dox = []

Используйтефлаг функции в вашем коде.

  1. Скомпилируйте модули tests, если выполняются тесты или , предоставляется флаг функции.
  2. Только отметка #[test] функцииесли флаг функции не предоставлен.Атрибут #[test] автоматически подразумевает #[cfg(test)], поэтому мы должны пропустить это, чтобы функция существовала. 
/// This function does some important stuff
pub fn working_fn() -> bool {
    true
}

#[cfg(any(test, feature = "dox"))]
mod tests {
    //! This is some important set of tests
    //!
    use super::*;

    /// The function should work
    #[cfg_attr(not(feature = "dox"), test)]
    fn it_works() {
        assert!(working_fn());
    }
}

Создание документации 

cargo doc --document-private-items --features=dox

Сохранениеобратите внимание на #[cfg(rustdoc)], который позволит вам убрать необходимость в собственном флаге функции, но в настоящее время нестабилен.

См. также:

в идеале я мог бы задокументировать частные тесты, не документируя также и другие частные объекты

Вы можете сделать свои тесты pub или pub(crate).

Если это не вариант, я думаю, что это будет более раздражающим, чем ценным.Прямое решение, о котором я знаю, было бы следовать Как изменить квалификаторы функции с помощью условной компиляции? , чтобы условно выполнить тест pub или нет.

...