Тестове в документацията

Главният начин да се документира проект в Ръждьо е чрез добавяне на бележки в изходния код. Документните коментари се пишат според Спецификацията на CommonMark Markdown и поддържат блокове от код в тях. Ръждьо се грижи за правилността, така че тези блокове от код се компилират и се ползват като тестове от документацията.

/// Първият ред е кратко общо описание на функцията.
///
/// Следващите редове представляват подробна документация. Блоковете код
/// започват с тройни обратни кавички и имат в себе си `fn main()` и `extern crate
/// <cratename>`. Да си представим, че тестваме коша `doccomments`:
///
/// ```
/// let result = doccomments::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

/// Обикновено документните коментари може да включват раздели „Examples”,
/// „Panics” и „Failures”.
///
/// Следващата функция дели едно число на друго.
///
/// # Examples
///
/// ```
/// let result = doccomments::div(10, 2);
/// assert_eq!(result, 5);
/// ```
///
/// # Panics
///
/// Функцията се паникьосва, ако вторият аргумент е нула.
///
/// ```rust,should_panic
/// // паникьосва се при делене на нула.
/// doccomments::div(10, 0);
/// ```
pub fn div(a: i32, b: i32) -> i32 {
    if b == 0 {
        panic!("Divide-by-zero error");
    }

    a / b
}

Блоковете код в документацията биват тествани автоматично, щом пуснете командата cargo test:

$ cargo test
running 0 tests

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

   Doc-tests doccomments

running 3 tests
test src/lib.rs - add (line 7) ... ok
test src/lib.rs - div (line 21) ... ok
test src/lib.rs - div (line 31) ... ok

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

Основания за тестове в документацията

Главната цел на документните тестове е да служат като примери, които ползват предоставяната функционалност, а това са най-важните насоки. Те ни позволяват да ползваме примерите от документацията като пълноценни парчета код. Но ползването на ? прави така, че компилацията се проваля, понеже main връща unit. В този случай можем да скрием няколко реда код от документацията: можем да напишем fn try_main() -> Result<(), ErrorType>, да я скрием и разгърнем (unwrap) в скритата main. Сложно ли звучи? Ето пример:

/// Използване на скрита `try_main` в документни тестове.
///
/// ```
/// # // Скритите редове започват със знака `#`, но са също компилируеми!
/// # // Ред, който обгръща тялото, показано в документацията.
/// # fn try_main() -> Result<(), String> {
/// let res = doccomments::try_div(10, 2)?;
/// # Ok(()) // Връщаме от try_main.
/// # }
/// # fn main() { // Започва `main`, която извиква `unwrap()`.
/// #    try_main().unwrap(); // Извикваме try_main и разгръщаме,
/// #                         // така че тестът ще се паникьоса в случай на
/// #                         // грешка.
/// # }
/// ```
pub fn try_div(a: i32, b: i32) -> Result<i32, String> {
    if b == 0 {
        Err(String::from("Divide-by-zero"))
    } else {
        Ok(a / b)
    }
}

See Also

  • RFC505 за стила на документацията;
  • API Guidelines за насоки при документиране.