Написание документации для Rust проекта: от А до Я

Онлайн-тренажер Python для начинающих

Изучайте Python легко и без перегрузки теорией. Решайте практические задачи с автоматической проверкой, получайте подсказки на русском языке и пишите код прямо в браузере — без необходимости что-либо устанавливать.

Начать курс

Введение: Зачем документация в Rust — это не просто прихоть

В мире системного программирования Rust занимает особое место благодаря своей безопасности, производительности и строгому компилятору. Однако даже самый элегантный код бесполезен, если разработчики не понимают, как его использовать. Документация — это мост между вашим кодом и его пользователями. В Rust этот процесс не просто рекомендован, а встроен в экосистему на уровне инструментов.

В этой статье мы разберем, как писать документацию для Rust проекта с нуля: от базовых doc-комментариев до создания полноценной книги с помощью mdbook. Вы узнаете, как использовать rustdoc, форматирование Markdown и тесты в документации, чтобы ваш проект стал понятным и профессиональным.

Основы: Документирование кода с помощью doc-комментариев

Rust предлагает два типа комментариев: обычные (//) и doc-комментарии (/// и //!). Doc-комментарии автоматически обрабатываются инструментом rustdoc, который генерирует HTML-документацию. Это основа любого Rust проекта.

Doc-комментарии для публичных элементов

Используйте /// для документирования функций, структур, трейтов и модулей. Пример:

/// Вычисляет факториал числа n.
/// 
/// # Аргументы
/// * `n` - неотрицательное целое число.
/// 
/// # Возвращает
/// * `u64` - факториал числа n.
/// 
/// # Примеры
/// ```
/// let result = factorial(5);
/// assert_eq!(result, 120);
/// ```
pub fn factorial(n: u32) -> u64 {
    (1..=n).product()
}

Обратите внимание на секции # Аргументы, # Возвращает и # Примеры. Это стандартные заголовки Markdown, которые улучшают читаемость.

Внутренняя документация модулей

Для документирования самого модуля (файла) используйте //!:

//! Модуль для математических операций.
//!
//! Этот модуль предоставляет функции для вычисления факториала,
//! чисел Фибоначчи и других математических алгоритмов.

Продвинутые техники: Тесты, ссылки и атрибуты

Одна из сильных сторон rustdoc — возможность запускать код из документации как тесты. Это гарантирует, что ваши примеры всегда актуальны и работают.

Тесты в документации (doctests)

Любой блок кода внутри doc-комментариев, помеченный как ```rust или просто ```, автоматически становится тестом при запуске cargo test. Пример:

/// Складывает два числа.
///
/// ```
/// let sum = add(2, 3);
/// assert_eq!(sum, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

Чтобы скрыть строки, которые не должны быть в примере (например, fn main()), используйте атрибут # :

/// ```
/// # fn main() {
/// let x = 42;
/// assert_eq!(x, 42);
/// # }
/// ```

Ссылки на другие элементы

Вы можете ссылаться на другие функции, структуры или модули с помощью синтаксиса [`имя`]. Rustdoc автоматически создаст гиперссылку:

/// Использует функцию [`factorial`] для вычисления комбинаций.

Атрибуты документации

Атрибуты позволяют управлять поведением rustdoc:

#[doc(hidden)] — скрывает элемент из документации.
#[doc(alias = "альтернативное_имя")] — добавляет псевдоним для поиска.
#[doc(cfg(feature = "some_feature"))] — показывает документацию только при включенной фиче.

Пример использования #[doc(alias)]:

#[doc(alias = "hello")]
pub fn greet(name: &str) -> String {
    format!("Hello, {}!", name)
}

Генерация и публикация: cargo doc и docs.rs

Когда документация написана, её нужно сгенерировать. Для этого используется команда cargo doc.

Локальная генерация

Выполните в терминале:

cargo doc --open

Эта команда сгенерирует документацию в папке target/doc и откроет её в браузере. Флаг --open опционален.

Для документации всех зависимостей используйте:

cargo doc --document-private-items

Флаг --document-private-items включает приватные элементы (по умолчанию документируются только публичные).

Публикация на docs.rs

Если ваш проект опубликован на crates.io, документация автоматически собирается и размещается на docs.rs. Для этого достаточно выполнить:

cargo publish

docs.rs автоматически запустит cargo doc для вашего проекта. Чтобы указать фичи, которые должны быть включены при сборке документации, добавьте в Cargo.toml:

[package.metadata.docs.rs]
features = ["full", "serde"]

Создание книги проекта с mdbook

Для больших проектов одной документации из doc-комментариев может быть недостаточно. В таких случаях используют mdbook — инструмент для создания книг из Markdown-файлов. Это идеальный способ написать руководство пользователя или архитектурный обзор.

Установка и инициализация

cargo install mdbook
mdbook init my-book
cd my-book
mdbook serve --open

Команда mdbook init создаст структуру папок с файлом SUMMARY.md, в котором определяется оглавление книги.

Пример структуры SUMMARY.md

# Summary

- [Введение](introduction.md)
- [Установка](installation.md)
- [Базовое использование](usage.md)
  - [Конфигурация](configuration.md)
- [API Reference](api.md)

Затем вы наполняете каждый Markdown-файл содержимым. mdbook поддержи