Всем привет! 🖖
В этой статье я расскажу об основных моментах документирования кода в Rust.
Из коробки Rust предоставляет инструмент rustdoc. Его основная задача - генерация документации для Rust проекта. Если просто, то он берет соответствующие Markdown комментарии к коду и сам код и преобразует их в красивое HTML-CSS-JS представление, в сайт.
Вызывать команду rustdoc можно напрямую, либо используя cargo. Я предпочитаю второй вариант.
Перейдите в вашу рабочую директорию, откройте в ней окно терминала и создайте новый Rust проект:
cargo new --lib rust_doc && cd rust_doc
Выполните в термине следующую команду:
cargo doc --open
В открывшемся окне браузера вы увидите базовый, пока что пустой, сайт с документацией к вашему проекту. Давайте напишем немного кода. Откройте проект rust_doc в вашем любимом редакторе, лично я работаю в Visual Code, а затем откройте файл lib.rs, который находится в папке src.
Создадим вначале файла lib.rs структуру Employee и определим у нее базовую функцию инициализации new, которая принимает на входе имя, фамилию и должность сотрудника, а возвращает instance структуры Employee:
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) -> Person {
return Employee {
name,
lastname,
job_title,
};
}
}
Теперь можем приступить к документированию кода.
Добавьте в самое начало файла lib.rs следующий фрагмент кода, после чего выполните в консоли cargo doc --open:
//! # rust_doc библиотека
//! *Она создана для понимания базовых
//! основ документирования кода в Rust*
Обратите внимание на изменения, которые произошли в документации.
Теперь давайте задокументируем структуру Employee, после внесения изменений в код вызовите документацию и посмотрите, что изменилось:
/// ## Структура сотрудника
/// Она предназначена для представления персональной инофмации о сотруднике
pub struct Employee {
/// Имя сотрудникаpub
name: String,
/// Фамилия сотрудникаpub
lastname: String,
/// Должность сотрудникаpub
job_title: String,
}
Самое время задокументировать инициализатор, но с добавлением вишенки на торте - написанием теста функции. После изменения кода изучите результат вызываю cargo doc --open.
/// Определение базовых функций
impl Employee {
/// Функция инициализации инстанса нового сотрудника
/// ```
/// use rust_doc::Employee;
/// let emp = Employee::new("Иван".to_string(),"Иванов".to_string(),"Директор".to_string());
/// assert!(emp.name == "Иван");
/// assert!(emp.lastname == "Иванов");
/// assert!(emp.job_title == "Директор");
/// ```
pub fn new(name: String, lastname: String, job_title: String) -> Employee {
return Employee {
lastname,
name,
job_title,
};
}
}
То, что в коде, в комментариях к функции, находится после ``` - это и есть наш тест. Давайте запустим его. Вызовите в консоли следующую команду:
cargo test --doc --package rust_doc -- Employee::new --nocapture
Тест пройден успешно.
Обратите внимание, что при написании документации я использовал обычный синтаксис Markdown разметки.
Документировать нужно, почти, все, чтобы не искать вручную не задокументированные строки кода, добавьте в начало main или lib файла следующий код, с помощью которого вы будете получать подсказки, если что-то не задокументировали:
#![warn(missing_docs)]
Важно! Если вы пишите описание самого проекта, которое обычно располагается в lib или main файле, то начинайте с символов //!, если же описываете непосредственно код, то документируйте с помощью ///.
Вот краткий экскурс в документирование Rust. Более подробно про документирование можно почитать здесь.
Автор: Айрат Галиуллин
