Learn Rust Coding · Lekcja

Komentarze dokumentacyjne

Dokumentacja ///

Komentarze dokumentacyjne to bezpłatna lekcja Learn Rust Coding na CoddyKit. To lekcja 3 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.

Dokumentacja w Rust

Rust ma pełnoprawny system dokumentacji wbudowany w język. Specjalne komentarze stają się dokumentacją HTML generowaną przez cargo doc.

Zewnętrzne komentarze dokumentacyjne

Użyj ///, aby udokumentować element, który znajduje się bezpośrednio po nim — funkcję, strukturę, wyliczenie i inne elementy. Tekst obsługuje składnię Markdown.

/// Adds two numbers together.
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

Formatowanie Markdown

Komentarze dokumentacyjne są renderowane jako Markdown: działają w nich nagłówki, listy, pogrubienie i odnośniki. Kod w tekście zapisuje się w backtickach, a nagłówki sekcji zaczynają się od #.

/// Computes the area of a rectangle.
///
/// # Arguments
/// * width - the width
/// * height - the height
pub fn area(width: u32, height: u32) -> u32 {
    width * height
}

Typowe sekcje dokumentacji

Konwencjonalne nagłówki ułatwiają przeglądanie dokumentacji:

# Examples — przykłady użycia
# Panics — sytuacje, w których występuje panika
# Errors — zwracane błędy
# Safety — niezmienniki dotyczące niebezpiecznego kodu

Wewnętrzne komentarze dokumentacyjne

Użyj //!, aby udokumentować otaczający element, zazwyczaj moduł lub cały pakiet. Umieść ten komentarz na początku pliku.

//! # My Math Crate
//!
//! Utilities for basic arithmetic.

pub fn double(n: i32) -> i32 {
    n * 2
}

Dokumentowanie struktur i pól

Każdy element publiczny, w tym pola struktur, może mieć własny komentarz dokumentacyjny.

/// A point in 2D space.
pub struct Point {
    /// The horizontal coordinate.
    pub x: f64,
    /// The vertical coordinate.
    pub y: f64,
}

Generowanie dokumentacji

cargo doc tworzy dokumentację HTML w katalogu target/doc. Dodaj --open, aby wyświetlić ją w przeglądarce.

cargo doc --open

Wykluczanie zależności

Domyślnie Cargo dokumentuje również zależności. Użyj --no-deps, aby utworzyć dokumentację tylko dla swojego pakietu.

cargo doc --no-deps --open

Odnośniki między elementami dokumentacji

Możesz tworzyć odnośniki do innych elementów, zapisując ich ścieżkę w nawiasach kwadratowych. Rust rozpoznaje ścieżkę i tworzy klikalny odnośnik w wygenerowanej dokumentacji.

/// See also [add] for addition.
///
/// [add]: crate::add
pub fn subtract(a: i32, b: i32) -> i32 {
    a - b
}

Po co tworzyć dokumentację?

Dobra dokumentacja przynosi wiele korzyści:

Jest automatycznie generowana jako przeszukiwalny HTML
Po opublikowaniu pakietu jest bezpłatnie udostępniana w docs.rs
Przykłady w dokumentacji są testowane (testy dokumentacji)
Pomaga współpracownikom i Tobie w przyszłości

Dokumentowanie modułu

Połącz komentarze wewnętrzne i zewnętrzne: plik modułu zaczyna się od //! opisującego moduł, a każdy element w jego wnętrzu korzysta z ///.

//! Geometry helpers.

/// Returns the perimeter of a square.
pub fn perimeter(side: f64) -> f64 {
    side * 4.0
}

Szybkie sprawdzenie

Jaka składnia komentarza dokumentuje element znajdujący się bezpośrednio po nim?

Podsumowanie

Dowiedziałeś się o komentarzach dokumentacyjnych:

/// dokumentuje następujący element, a //! dokumentuje element otaczający
Obsługują Markdown i sekcje, takie jak # Examples
Odnośniki między elementami łączą je ze sobą
cargo doc --open generuje dokumentację HTML i otwiera ją do wyświetlenia

Często zadawane pytania

Czy lekcja „Komentarze dokumentacyjne” jest bezpłatna?

Tak — pełny tekst „Komentarze dokumentacyjne” 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 „Komentarze dokumentacyjne”?

Dokumentacja /// Ć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 3 z 4.

Ile czasu zajmuje lekcja „Komentarze dokumentacyjne”?

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