rust

Всем привет! 🖖В этой статье я расскажу об основных моментах документирования кода в Rust. Из коробки Rust предоставляет инструмент rustdoc. Его основная задача - генерация документации для Rust проекта. Если просто, то он берет соответствующие Markdown комментарии к коду и сам код и преобразует их в красивое HTML-CSS-JS представление, в сайт. Вызывать команду rustdoc можно напрямую, либо используя cargo. Я предпочитаю второй вариант. Перейдите в вашу рабочую директорию, откройте в ней окно терминала и создайте новый Rust проект:cargo new --lib rust_doc &amp;&amp; cd rust_doc Выполните в термине следующую команду:cargo doc --open В открывшемся окне браузера вы увидите базовый, пока что пустой, сайт с документацией к вашему проекту. Давайте напишем немного кода. Откройте проект rust_doc в вашем любимом редакторе, лично я работаю в Visual Code, а затем откройте файл lib.rs, который находится в папке src. Создадим вначале файла lib.rs структуру Employee и определим у нее базовую функцию инициализации new, которая принимает на входе имя, фамилию и должность сотрудника, а возвращает instance структуры Employee: <pre class="ql-syntax" spellcheck="false">pub struct Employee {
 pub name: String,
 pub lastname: String,
 pub job_title: String,
}

impl Employee {
 pub fn new(name: String, lastname: String, job_title: String) -&gt; Person {
 return Employee {
 name,
 lastname,
 job_title,
 };
 }
}
</pre> Теперь можем приступить к документированию кода.Добавьте в самое начало файла lib.rs следующий фрагмент кода, после чего выполните в консоли cargo doc --open: <pre class="ql-syntax" spellcheck="false">//! # rust_doc библиотека 
﻿//! *Она создана для понимания базовых 
﻿//! основ документирования кода в Rust*
</pre> Обратите внимание на изменения, которые произошли в документации.Теперь давайте задокументируем структуру Employee, после внесения изменений в код вызовите документацию и посмотрите, что изменилось: <pre class="ql-syntax" spellcheck="false">/// ## Структура сотрудника
/// Она предназначена для представления персональной инофмации о сотруднике
pub struct Employee {
 /// Имя сотрудникаpub 
 ﻿name: String,
 /// Фамилия сотрудникаpub 
 lastname: String, 
 /// Должность сотрудникаpub 
 job_title: String, 
}
</pre> Самое время задокументировать инициализатор, но с добавлением вишенки на торте - написанием теста функции. После изменения кода изучите результат вызываю cargo doc --open. <pre class="ql-syntax" spellcheck="false">/// Определение базовых функций
impl Employee {
&nbsp;&nbsp;&nbsp; /// Функция инициализации инстанса нового сотрудника
&nbsp;&nbsp;&nbsp; /// ```
&nbsp;&nbsp;&nbsp; /// use rust_doc::Employee;
&nbsp;&nbsp;&nbsp; /// let emp = Employee::new("Иван".to_string(),"Иванов".to_string(),"Директор".to_string());
&nbsp;&nbsp;&nbsp; /// assert!(emp.name == "Иван");
&nbsp;&nbsp;&nbsp; /// assert!(emp.lastname == "Иванов");
&nbsp;&nbsp;&nbsp; /// assert!(emp.job_title == "Директор");
&nbsp;&nbsp;&nbsp; /// ```
&nbsp;&nbsp;&nbsp; pub fn new(name: String, lastname: String, job_title: String) -&gt; Employee {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return Employee {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; lastname,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; name,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; job_title,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; };
&nbsp;&nbsp;&nbsp; }
} 
</pre> То, что в коде, в комментариях к функции, находится после ``` - это и есть наш тест. Давайте запустим его. Вызовите в консоли следующую команду:cargo test --doc --package rust_doc -- Employee::new --nocapture Тест пройден успешно. Обратите внимание, что при написании документации я использовал обычный синтаксис Markdown разметки. Документировать нужно, почти, все, чтобы не искать вручную не задокументированные строки кода, добавьте в начало main или lib файла следующий код, с помощью которого вы будете получать подсказки, если что-то не задокументировали:#![warn(missing_docs)] Важно! Если вы пишите описание самого проекта, которое обычно располагается в lib или main файле, то начинайте с символов //!, если же описываете непосредственно код, то документируйте с помощью ///. Вот краткий экскурс в документирование Rust. Более подробно про документирование можно почитать <a href="https://doc.rust-lang.org/rustdoc/write-documentation/what-to-include.html" rel="noopener noreferrer" target="_blank">здесь</a>.

558111a40d3ab1b1ab9aaa9bda155881_rust_doc.jpg

В этой статье рассмотрим то, как происходит документирование в Rust и рассмотрим очень полезную возможность - написание тестов через документирование.

Хэштег: #rust

Документирование кода в языке программирования Rust