Rust на примерах

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

Документационные комментарии очень полезны для больших проектов, требующих документирования. Эти комментарии компилируются в документацию при запуске 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

• The Rustdoc Book

• The Reference: Doc 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)