Модуль 3 · Команды Cargo

Документация

cargo doc генерирует HTML-документацию прямо из кода и комментариев — автоматически, без дополнительных инструментов.

📖 Теория 🕐 ~15 минут

📋

cargo doc — генерация документации

Терминал

cargo doc                      # сгенерировать документацию
cargo doc --open               # сгенерировать и открыть в браузере
cargo doc --no-deps            # только ваш крейт, без зависимостей
cargo doc --document-private-items  # включить приватные функции

Документация генерируется в target/doc/имя_крейта/index.html. Выглядит точно так же как страницы на docs.rs.

💡 Когда вы публикуете крейт на crates.io, сервис docs.rs автоматически запускает cargo doc и хостит результат. Ваша документация появится на docs.rs/имя_крейта без каких-либо действий с вашей стороны.

✍️

Doc-комментарии — синтаксис

src/lib.rs

/// Документация для функции/структуры/модуля (/// — три слэша)
/// Поддерживает **Markdown**: жирный, *курсив*, `код`, списки.
///
/// # Arguments
///
/// * `name` — имя пользователя
/// * `age` — возраст
///
/// # Returns
///
/// Форматированная строка приветствия.
///
/// # Examples
///
/// ```
/// use my_crate::greet;
/// assert_eq!(greet("Иван", 25), "Привет, Иван! Тебе 25 лет.");
/// ```
///
/// # Errors
///
/// Возвращает ошибку если age > 150.
///
/// # Panics
///
/// Паникует если name пустой.
pub fn greet(name: &str, age: u32) -> String {
    format!("Привет, {}! Тебе {} лет.", name, age)
}

//! Документация для модуля/крейта (//! — два слэша + восклицательный)
//! Обычно пишется в начале файла src/lib.rs
//! Описывает весь крейт целиком.

///Документация для следующего элемента (функция, структура, поле)

//!Документация для содержащего элемента — весь модуль или крейт

# ExamplesСекция с примерами — блоки кода в ней автоматически становятся тестами при cargo test --doc

🌐

docs.rs — читать документацию зависимостей

Документацию любого крейта из crates.io можно найти на docs.rs:

📖

docs.rs/serde — документация serde

📖

docs.rs/tokio/latest/tokio — документация tokio

💡 Также: cargo doc --open откроет документацию всех ваших зависимостей локально — не нужен интернет.

📌 Что важно запомнить

→ cargo doc --open — сгенерировать и открыть в браузере

→ /// — doc-комментарий для элемента; //! — для модуля/крейта

→ Примеры в /// автоматически становятся тестами (cargo test --doc)

→ При публикации на crates.io → docs.rs автоматически генерирует документацию