Документация Rust | Cargo | Rustdoc | Документация кода

Введение

В этом лабораторном задании вы можете использовать cargo doc для создания документации в target/doc. Также вы можете использовать cargo test для запуска всех тестов, включая тесты документации, и cargo test --doc для запуска только тестов документации. Doc-комментарии, обозначенные ///, компилируются в документацию с помощью rustdoc и поддерживают Markdown. Эти комментарии полезны для документирования кода в крупных проектах. Doc-атрибуты, такие как inline, no_inline и hidden, часто используются вместе с rustdoc. Rustdoc широко используется сообществом для генерации документации, в том числе и для документации стандартной библиотеки.

Примечание: Если лабораторное задание не задает имя файла, вы можете использовать любое имя файла, которое хотите. Например, вы можете использовать main.rs, скомпилировать и запустить его с помощью rustc main.rs &&./main.

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

Используйте cargo doc для создания документации в target/doc.

Используйте cargo test для запуска всех тестов (включая тесты документации), и cargo test --doc для запуска только тестов документации.

Эти команды будут вызывать rustdoc (и rustc) по необходимости.

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

Doc-комментарии очень полезны для крупных проектов, требующих документации. При запуске rustdoc эти комментарии компилируются в документацию. Они обозначаются /// и поддерживают [Markdown].

#![crate_name = "doc"]

/// Здесь представлен человек
pub struct Person {
    /// У человека должен быть имя, неважно, насколько это может ненавидеть Джульетта
    name: String,
}

impl Person {
    /// Возвращает человека с заданным именем
    ///
    /// ## Аргументы
    ///
    /// * `name` - Строковый срез, содержащий имя человека
    ///
    /// ## Примеры
    ///
    /// ```
    /// // В комментариях между границами можно писать код на Rust
    /// // Если передать --test в `rustdoc`, он даже запустит тесты для вас!
    /// use doc::Person;
    /// let person = Person::new("name");
    /// ```
    pub fn new(name: &str) -> Person {
        Person {
            name: name.to_string(),
        }
    }

    /// Дает дружелюбное приветствие!
    ///
    /// Говорит "Привет, [имя](Person::name)" для `Person`, на котором вызывается.
    pub fn hello(& self) {
        println!("Hello, {}!", self.name);
    }
}

fn main() {
    let john = Person::new("John");

    john.hello();
}

Для запуска тестов сначала соберите код в виде библиотеки, а затем укажите rustdoc, где найти библиотеку, чтобы он мог связать ее с каждым тестовым программой doctest:

$ rustc doc.rs --crate-type lib
$ rustdoc --test --extern doc="libdoc.rlib" doc.rs

Doc-атрибуты

Ниже приведены несколько примеров наиболее распространенных #[doc]-атрибутов, используемых с rustdoc.

`inline`

Используется для встраивания документации вместо ссылки на отдельную страницу.

#[doc(inline)]
pub use bar::Bar;

/// Документация для bar
mod bar {
    /// Документация для Bar
    pub struct Bar;
}

`no_inline`

Используется для предотвращения ссылки на отдельную страницу или вообще любых ссылок.

// Пример из libcore/prelude
#[doc(no_inline)]
pub use crate::mem::drop;

`hidden`

Использование этого атрибута сообщает rustdoc не включать это в документацию:

// Пример из библиотеки futures-rs
#[doc(hidden)]
pub use self::async_await::*;

Для документации rustdoc широко используется сообществом. Именно с его помощью генерируются документации стандартной библиотеки.

Резюме

Поздравляем! Вы завершили лабораторную работу по Документации. Вы можете практиковаться в других лабораторных работах в LabEx, чтобы улучшить свои навыки.

Генерация и тестирование документации Cargo