Learn Rust Coding · Lekcja

Testy dokumentacji

Testowane przykłady

Testy dokumentacji to bezpłatna lekcja Learn Rust Coding na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Learn Rust Coding, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Learn Rust Coding zawiera 4 lekcji w sumie.

Czym są testy dokumentacji?

Testy dokumentacji to przykłady kodu umieszczone w komentarzach dokumentacyjnych, które Cargo rzeczywiście kompiluje i uruchamia. Dzięki nim dokumentacja pozostaje poprawna, a przykłady działają.

Kod w komentarzach dokumentacyjnych

Umieść przykładowy kod w ogrodzonym bloku kodu (trzy backticki) wewnątrz komentarza ///, pod nagłówkiem # Examples. Domyślnym językiem jest Rust.

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

Uruchamianie testów dokumentacji

Testy dokumentacji są uruchamiane jako część cargo test. Są raportowane osobno w sekcji Doc-tests.

cargo test

Asercje w przykładach

Przykłady zwykle zawierają asercje, aby błędny przykład powodował niepowodzenie testu, a nie tylko poprawnie się kompilował.

/// 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 }
}

Ukrywanie wierszy konfiguracji

Dodaj # na początku wiersza, aby go wykonać, ale ukryć w wyrenderowanej dokumentacji. Jest to przydatne w przypadku kodu pomocniczego, takiego jak importy.

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

Przykłady użycia operatora znaku zapytania

Aby użyć operatora ?, umieść kod w ukrytej funkcji main (lub pomocniczej), która zwraca Result. Ukryte wiersze zaczynają się od #.

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

Przykłady no_run

Oznacz ogrodzony blok adnotacją no_run, aby go skompilować, ale nie wykonywać — jest to przydatne w przypadku przykładów wymagających sieci lub plików.

/// 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 i should_panic

Inne adnotacje ogrodzenia kodu:

ignore — ani nie kompiluje, ani nie uruchamia
should_panic — oczekuje paniki
compile_fail — oczekuje, że kod się nie skompiluje

Dlaczego testy dokumentacji są ważne

Testy dokumentacji dają dwie korzyści naraz:

Dokumentację, która jest zawsze aktualna
Bezpłatne pokrycie testami publicznych przykładów

Jeśli przykład przestanie działać, zestaw testów zakończy się niepowodzeniem.

Nazwa crate w przykładach

Testy dokumentacji są uruchamiane tak, jakby znajdowały się poza crate, dlatego należy odwoływać się do elementów za pomocą nazwy crate (np. my_crate::func) lub importu use.

Bloki ogrodzone a bloki z wcięciem

Testy dokumentacji akceptują dwa style bloków:

Blok ogrodzony przy użyciu trzech backticków, który pozwala na adnotacje, takie jak no_run
Blok z wcięciem (cztery spacje), pokazany w tych przykładach

W rzeczywistym kodzie częściej używa się bloków ogrodzonych.

Szybkie sprawdzenie

Co robi wiersz zaczynający się od # wewnątrz bloku kodu testu dokumentacji?

Podsumowanie

W tym module poznano testy dokumentacji:

Kod w blokach /// jest kompilowany i uruchamiany przez cargo test
Używanie asercji do weryfikowania działania
# ukrywa wiersze przygotowujące kod w wyrenderowanej dokumentacji
Adnotacje: no_run, ignore, should_panic, compile_fail
Automatycznie zapewniają poprawność przykładów

Często zadawane pytania

Czy lekcja „Testy dokumentacji” jest bezpłatna?

Tak — pełny tekst „Testy dokumentacji” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Learn Rust Coding, przejdź na CoddyKit PRO. Kurs Learn Rust Coding zawiera 4 lekcji w sumie.

Co nauczysz się w „Testy dokumentacji”?

Testowane przykłady Ćwiczysz Learn Rust Coding z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Learn Rust Coding?

Nie wymagamy żadnego doświadczenia. Learn Rust Coding w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.

Ile czasu zajmuje lekcja „Testy dokumentacji”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Learn Rust Coding?

Tak. Każda lekcja Learn Rust Coding zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do Learn Rust Coding