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

Вступление

Синтаксис

• /// Комментарий к внешней документации (относится к элементу ниже)

• //! Внутренний комментарий к документации (относится к прилагаемому элементу)

• cargo doc # Создает документацию для этого библиотечного ящика.

• load doc --open # Создает документацию для этого библиотечного ящика и открывает браузер.

• load doc -p CRATE # Создает документацию только для указанного ящика.

• load doc --no-deps # Создает документацию для этой библиотеки и никаких зависимостей.

• испытание груза # Выполняет модульные испытания и испытания документации.

замечания

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

Чтобы обеспечить документирование всех возможных элементов, вы можете использовать ссылку missing_docs для получения предупреждений / ошибок от компилятора. Чтобы получать предупреждения по всей библиотеке, поместите этот атрибут в свой файл lib.rs :

#![warn(missing_docs)]

Вы также можете получить ошибки для отсутствия документации с помощью этой строки:

#![deny(missing_docs)]

По умолчанию missing_docs разрешены, но вы можете явно разрешить им этот атрибут:

#![allow(missing_docs)]

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

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

Rust предоставляет два типа комментариев документации: комментарии внутренней документации и внешние комментарии к документации. Примеры каждого из них приведены ниже.

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

mod foo {
    //! Inner documentation comments go *inside* an item (e.g. a module or a 
    //! struct). They use the comment syntax //! and must go at the top of the
    //! enclosing item. 
    struct Bar {
        pub baz: i64
        //! This is invalid. Inner comments must go at the top of the struct,
        //! and must not be placed after fields.
    }
}

Комментарии к внешней документации

/// Outer documentation comments go *outside* the item that they refer to.
/// They use the syntax /// to distinguish them from inner comments.
pub enum Test {
    Success,
    Fail(Error)
}

Условные обозначения

/// In documentation comments, you may use **Markdown**.
/// This includes `backticks` for code, *italics* and **bold**.
/// You can add headers in your documentation, like this:
/// # Notes
/// `Foo` is unsuitable for snafucating. Use `Bar` instead.
struct Foo {
    ...
}

/// It is considered good practice to have examples in your documentation
/// under an "Examples" header, like this:
/// # Examples
/// Code can be added in "fences" of 3 backticks.
///
/// ```
/// let bar = Bar::new();
/// ```
///
/// Examples also function as tests to ensure the examples actually compile.
/// The compiler will automatically generate a main() function and run the
/// example code as a test when cargo test is run.
struct Bar {
    ...
}

Тестирование документации

Код в комментариях к документации автоматически будет выполнен с помощью cargo test . Они известны как «тесты документации» и помогают обеспечить работу ваших примеров и не будут вводить пользователей в заблуждение.

Вы можете импортировать относительный из корня ящика (как если бы у extern crate mycrate; был скрытый extern crate mycrate; в верхней части примера)

/// ```
/// use mycrate::foo::Bar;
/// ```

Если ваш код может не выполняться должным образом в тесте документации, вы можете использовать атрибут no_run , например:

/// ```no_run
/// use mycrate::NetworkClient;
/// NetworkClient::login("foo", "bar");
/// ```

Вы также можете указать, что ваш код должен паниковать, например:

/// ```should_panic
/// unreachable!();
/// ```