Learn Rust Coding · Урок

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

Проверяемые примеры

«Тесты документации» — бесплатный урок Learn Rust Coding на CoddyKit. Это урок 4 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Learn Rust Coding, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Learn Rust Coding содержит 4 уроков всего.

Что такое тесты документации?

Тесты документации — это примеры кода внутри комментариев документации, которые Cargo действительно компилирует и запускает. Они поддерживают актуальность документации и работоспособность примеров.

Код в комментариях документации

Поместите пример кода в блок кода с ограждением (три обратные кавычки) внутри комментария ///, под заголовком # Examples. Язык по умолчанию — Rust.

/// Doubles a number.
///
/// # Examples
///
///     let result = my_crate::double(4);
///     assert_eq!(result, 8);
pub fn double(n: i32) -> i32 {
    n * 2
}

Запуск тестов документации

Тесты документации запускаются как часть cargo test. Их результаты выводятся отдельно в разделе Doc-tests.

cargo test

Проверки в примерах

Обычно примеры содержат проверки, чтобы неправильный пример не просто успешно компилировался, а приводил к ошибке теста.

/// Returns the larger of two values.
///
/// # Examples
///
///     assert_eq!(my_crate::max(3, 7), 7);
///     assert_eq!(my_crate::max(9, 2), 9);
pub fn max(a: i32, b: i32) -> i32 {
    if a > b { a } else { b }
}

Скрытие строк настройки

Добавьте # в начало строки, чтобы она выполнялась, но не отображалась в готовой документации. Это удобно для шаблонного кода, например импортов.

/// # Examples
///
///     # use my_crate::Counter;
///     let mut c = Counter::new();
///     c.increment();
///     assert_eq!(c.value(), 1);

Примеры с вопросительным знаком

Чтобы использовать оператор ?, поместите тело в скрытую main (или вспомогательную функцию), возвращающую Result. Скрытые строки начинаются с #.

/// # Examples
///
///     # fn run() -> Result<(), std::num::ParseIntError> {
///     let n: i32 = "42".parse()?;
///     assert_eq!(n, 42);
///     # Ok(())
///     # }

Примеры no_run

Пометьте блок кода с ограждением аннотацией no_run, чтобы он компилировался, но не выполнялся, — это удобно для примеров, которым нужны сеть или файлы.

/// Fetches a page (compiled but not executed).
///
/// Annotate the code fence with no_run so it is type-checked only.
pub fn fetch(url: &str) -> String {
    format!("contents of {url}")
}

ignore и should_panic

Другие аннотации для блока кода:

ignore — не компилировать и не запускать
should_panic — ожидается паника
compile_fail — ожидается ошибка компиляции

Зачем нужны тесты документации

Тесты документации дают сразу два преимущества:

Всегда точная документация
Бесплатное покрытие тестами общедоступных примеров

Если пример перестанет работать, набор тестов завершится с ошибкой.

Имя крейта в примерах

Тесты документации запускаются так, будто находятся за пределами крейта, поэтому обращайтесь к элементам через имя крейта (например, my_crate::func) или импортируйте их с помощью use.

Блоки с ограждением и блоки с отступом

Тесты документации поддерживают два вида блоков:

Блок с ограждением из трёх обратных кавычек, допускающий аннотации вроде no_run
Блок с отступом в четыре пробела, показанный в этих примерах

В реальном коде чаще используются блоки с ограждением.

Быстрая проверка

Что делает строка, начинающаяся с #, внутри блока кода теста документации?

Повторение

Вы изучили тесты документации:

Код в блоках /// компилируется и запускается с помощью cargo test
Используйте проверки для подтверждения поведения
# скрывает строки настройки в готовой документации
Аннотации: no_run, ignore, should_panic, compile_fail
Они автоматически поддерживают корректность примеров

Часто задаваемые вопросы

Урок «Тесты документации» бесплатный?

Да — полный текст урока «Тесты документации» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Learn Rust Coding, подпишись на CoddyKit PRO. Курс Learn Rust Coding содержит 4 уроков всего.

Чему я научусь в уроке «Тесты документации»?

Проверяемые примеры Ты практикуешь Learn Rust Coding с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Learn Rust Coding?

Предыдущий опыт не требуется. Learn Rust Coding на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 4 из 4.

Сколько времени занимает урок «Тесты документации»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Learn Rust Coding?

Да. Каждый урок Learn Rust Coding включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к Learn Rust Coding