Документація
Використовуйте cargo doc, щоб зібрати документацію в target/doc, cargo doc --open
автоматично відкриє її у вашому веббраузері.
Використовуйте cargo test, щоб запустити всі тести (включно з documentation tests), і cargo test --doc, щоб запускати лише documentation tests.
Ці команди належним чином викличуть rustdoc (і rustc) за потреби.
Doc comments
Doc comments дуже корисні для великих проєктів, які потребують документації. Під час
запуску rustdoc саме ці коментарі компілюються в
документацію. Вони позначаються за допомогою /// і підтримують Markdown.
#![crate_name = "doc"]
/// Людину тут представлено як
pub struct Person {
/// Людина повинна мати ім'я, незалежно від того, як сильно Джульєт це може ненавидіти
name: String,
}
impl Person {
/// Створює людину з указаним ім'ям.
///
/// # Приклади
///
/// ```
/// // Ви можете мати rust code між fences усередині коментарів
/// // Якщо ви передасте --test до `rustdoc`, він навіть протестує це для вас!
/// use doc::Person;
/// let person = Person::new("name");
/// ```
pub fn new(name: &str) -> Person {
Person {
name: name.to_string(),
}
}
/// Дарує дружнє привітання!
///
/// Каже "Hello, [name](Person::name)" до `Person`, на якому його викликано.
pub fn hello(&self) {
println!("Hello, {}!", self.name);
}
}
fn main() {
let john = Person::new("John");
john.hello();
}Щоб запустити тести, спочатку зберіть код як бібліотеку, потім повідомте rustdoc, де
знайти бібліотеку, щоб він міг зв’язати її з кожною doctest program:
$ rustc doc.rs --crate-type lib
$ rustdoc --test --extern doc="libdoc.rlib" doc.rs
Doc attributes
Нижче наведено кілька прикладів найпоширеніших #[doc] attributes, що використовуються з
rustdoc.
inline
Використовується для вбудовування docs, замість посилання на окрему сторінку.
#[doc(inline)]
pub use bar::Bar;
/// docs для bar
pub mod bar {
/// docs для 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 широко використовується спільнотою. Саме його використовують,
щоб згенерувати docs бібліотеки std: https://doc.rust-lang.org/std/.