Введение
В этом лабораторном задании основной способ документирования проекта на Rust - это комментирование исходного кода с использованием комментариев документации, которые пишутся в соответствии с спецификацией CommonMark Markdown и поддерживают в себе блоки кода. Rust заботится о правильности, и эти блоки кода компилируются и используются в качестве тестов документации. Эти тесты автоматически запускаются при использовании команды cargo test. Основная идея тестов документации - это служить примерами, которые демонстрируют функциональность и позволяют использовать примеры из документации в качестве полноценных фрагментов кода.
Примечание: Если лабораторное задание не задает имя файла, вы можете использовать любое имя, которое хотите. Например, вы можете использовать
main.rs, скомпилировать и запустить его с помощьюrustc main.rs &&./main.
Тестирование документации
Основной способ документирования проекта на Rust - это комментирование исходного кода. Комментарии документации пишутся в соответствии с спецификацией CommonMark Markdown и поддерживают в себе блоки кода. Rust заботится о правильности, поэтому эти блоки кода компилируются и используются в качестве тестов документации.
/// Первая строка - это краткое описание функции.
///
/// Следующие строки представляют подробную документацию. Блоки кода начинаются с
/// тройных обратных кавычек и внутри них есть неявный `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
}
/// Обычно комментарии документации могут включать разделы "Примеры", "Паники" и "Неудачи".
///
/// Следующая функция делит два числа.
///
/// ## Примеры
///
/// ```
/// let result = doccomments::div(10, 2);
/// assert_eq!(result, 5);
/// ```
///
/// ## Паники
///
/// Функция паникует, если второй аргумент равен нулю.
///
/// ```rust
/// // паникует при делении на ноль
/// doccomments::div(10, 0);
/// ```
pub fn div(a: i32, b: i32) -> i32 {
if b == 0 {
panic!("Divide-by-zero error");
}
a / b
}
Блоки кода в документации автоматически тестируются при запуске обычной команды cargo test:
[object Object]
Причина тестирования документации
Основная цель тестов документации - это служить примерами, которые демонстрируют функциональность, что является одной из самых важных рекомендаций. Это позволяет использовать примеры из документации в качестве полноценных фрагментов кода. Но использование ? приводит к ошибке компиляции, так как 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 и unwrap
/// ## // чтобы тест паниковал в случае ошибки
/// ## }
/// ```
pub fn try_div(a: i32, b: i32) -> Result<i32, String> {
if b == 0 {
Err(String::from("Divide-by-zero"))
} else {
Ok(a / b)
}
}
Резюме
Поздравляем! Вы завершили лабораторную работу по Тестированию документации. Вы можете практиковаться в других лабораторных работах в LabEx, чтобы улучшить свои навыки.