Документация
Ползвайте cargo doc, за да изградите документация в target/doc.
Ползвайте cargo test, за да пуснете всички тестове (включително тези от
документацията), а cargo test --doc – само за документните тестове.
Тези команди ще извикат съответно rustdoc (и rustc) според необходимостта.
Документни коментари
Документните коментари са много полезни за големи проекти. Когато пуснем
rustdoc, тези коментари се компилират като документация. Те се означават с
/// и биват разбрани като Markdown.
#![crate_name = "doc"]
/// Тук се представя човешко същество.
pub struct Person {
/// Личността трябва да има име, колкото и да го мрази Жулиета.
name: String,
}
impl Person {
/// Връща личност с даденото ѝ име.
///
/// # Аргументи
///
/// * `name` – Отрязък от низ, съдържащ името на лицето.
///
/// # Примери
///
/// ```
/// // Може да имаме ограден код на Ръждьо вътре в коментарите
/// // Ако подадем --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)" на лицето, с което е извикана.
pub fn hello(& self) {
println!("Hello, {}!", self.name);
}
}
fn main() {
let john = Person::new("John");
john.hello();
}
За да пуснете тестовете, първо изградете кода като библиотека, после кажете
на rustdoc къде да намери библиотеката, така че да може да я свърже с всеки
документен тест:
$ rustc doc.rs --crate-type lib
$ rustdoc --test --extern doc="libdoc.rlib" doc.rs
Документни атрибути
Следват няколко примера с най-използваните аргументи за атрибута #[doc].
inline
Използва се за вместване на документацията, вместо да се прави връзка към отделна страница.
#[doc(inline)]
pub use bar::Bar;
/// документация за bar
mod bar {
/// документацията за Bar
pub struct Bar;
}
no_inline
Използва се, за да предотврати свързване към отделна страница или където и да е.
// Example from libcore/prelude
#[doc(no_inline)]
pub use crate::mem::drop;
hidden
С това казваме на rustdoc да не включва това в документацията:
// Example from the futures-rs library
#[doc(hidden)]
pub use self::async_await::*;
rustdoc се използва широко от общността. С тази програма е създадена
документацията за стандартната библиотека.