Документационные комментарии очень полезны для больших проектов, требующих документирования. Эти комментарии компилируются в документацию при запуске 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(),
}
}
/// Дружественное приветствие!
///
/// Говорит "Привет, [name]" для `Person` у которого он вызывается.
pub fn hello(& self) {
println!("Привет, {}!", self.name);
}
}
fn main() {
let john = Person::new("John");
john.hello();
}
הההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההההה
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Для запуска тестов сначала соберите код как библиотеку, а затем скажите rustdoc где найти эту библиотеку, чтобы он мог подключить её к каждому документационному тесту:
$ rustc doc.rs --crate-type lib
$ rustdoc --test --extern doc="libdoc.rlib" doc.rs
• The Rust Book: Making Useful Documentation Comments
• RFC 1574: API Documentation Conventions
• RFC 1946: Relative links to other items from doc comments (intra-rustdoc links)
• Is there any documentation style guide for comments? (reddit)