где это возможно.
• Сырые идентификаторы
Сырые идентификаторы
В Rust, как и во многих других языках программирования, существует концепция "ключевых слов". Эти идентификаторы что-то значат для языка и из-за этого вы не можете использовать их в качестве названия переменных, именах функций и других местах. Сырые идентификаторы позволяют использовать ключевые слова там, где они обычно не разрешены. Это особенно полезно, когда Rust вводит новые ключевые слова и библиотеки, использующие старую редакцию Rust, имеют переменные или функции с таким же именем, как и ключевое слово, введённое в новой редакции.
Например, рассмотрим крейт foo, скомпилированный с 2015 редакцией Rust, и который экспортирует функцию с именем try. Это ключевое слово зарезервировано для новой функциональности в 2018 редакции, из-за чего без сырых идентификаторов мы не можем назвать так функцию.
extern crate foo;
fn main() {
foo::try();
}
Вы получите ошибку:
error: expected identifier, found keyword `try`
--> src/main.rs:4:4
|
4 | foo::try();
| ^^^ expected identifier, found keyword
Вы можете записать это при помощи сырого идентификатора:
extern crate foo;
fn main() {
foo::r#try();
}
Meta
Некоторые темы не совсем соответствуют тому, как вы программируете, но предоставляют вам инструменты или инфраструктуру, которые делают лучше для всех. Эти темы включают:
• Документацию: генерирование пользовательской документации с использованием rustdoc.
• Playpen: интегрирование Rust Playpen (также известного как Rust Playground) в свою документацию.
Документация
Используйте cargo doc для сборки документации в target/doc.
Используйте cargo test для запуска всех тестов (включая документационные тесты) и cargo test --doc для запуска только документационных тестов.
Эти команды, по мере необходимости, будут соответствующим образом вызывать rustdoc (и rustc).
Документационные комментарии
Документационные комментарии очень полезны для больших проектов, требующих документирования. Эти комментарии компилируются в документацию при запуске 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)
Playpen