<НазадДокументирование кода в языке программирования Rust
8/24/2022Всем привет! 🖖
В этой статье я расскажу об основных моментах документирования кода в 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. Более подробно про документирование можно почитать здесь.
Самое свежее
Состав команды разработки
7/6/2023В этой статье мы рассмотрим состав команды разработки ИТ решения
Простыми словами о графах
12/18/2022В этой статье мы начнем знакомство с графами, познакомимся с одним из алгоритмов для работы с графами и реализуем граф на языке программирования Rust.
В чем отличие аутсорсинга разработки от аутстаффинга ИТ-сотрудника для разработки?
10/17/2022В этой статье разберемся, что такое аутсорс- и аутстафф-разработка.
UI/UX дизайн: Процесс создания
4/9/2023В этой статье поговорим об основных шагах в процессе создания UI/UX дизайна.
UI/UX дизайн: Введение
3/29/2023В этой статье мы начинаем знакомиться с UI/UX дизайном. Это важнейший этап в разработке любого визуального интерфейса приложений.
Agile, Шесть сигм и Отсутствие принципа
9/14/2023В прошлой статье мы начали погружение в процесс разработки. Первый этап этого процесса — планирование. На этом этапе проектный менеджер вместе с другими участниками команды формирует пул задач в соответсвии с какой-то методологией ведения проектов.
Знакомьтесь, Пентест
8/22/2022Начинаем рассматривать один из основных методов оценки безопасности компьютерных систем и сетей на предмет потенциальных уязвимостей - тестирование на проникновение
Сокращаем срок реализации MVP
12/8/2022Разберемся со сроками реализации MVP.
Выбираем язык программирования
3/17/2023В этой статье мы поговорим о выборе языка программирования для изучения
Тестирование концепции MVP
1/9/2023Разбираемся с тем, как не потратить бюджеты на разработку MVP впустую
Проектирование архитектуры приложений: Введение
3/6/2023В этой статье поговорим о процессе создания архитектуры ИТ-решения
Техническое задание: Структура
2/17/2023В этой публикации мы рассмотрим универсальную структуру ТЗ
Неверная оценка стоимости услуг ИТ подрядчика
9/10/2022Сегодня мы поговорим о неверной оценке стоимости разработки ИТ решений. Эта боль - одна из основных для предприятий и стартапов, включая самих ИТ подрядчиков.
Введение в паттерны проектирования в разработке программного обеспечения
10/3/2022В этой статье мы начнем погружаться в мир оптимизации архитектуры приложений с помощью шаблонов проектирования
Выбираем направление разработки для обучения программированию
2/5/2023В этой статье вы узнаете какие бывают направления разработки, чем они отличаются и в каком больше платят.
Уровни модели OSI
9/6/2022В этой статье мы более подробно рассмотрим каждый из уровней модели OSI
Основные типы архитектуры приложений
3/7/2023В этой публикации разберемся с тем, какие бывают архитектуры приложений
10 способов использования Rust Cargo
2/11/2023В этой небольшой статье я собрал 10 способов использования системы сборки и менеджера пакетов языка программирования Rust
Знакомство с моделью OSI
8/19/2022В этой статье начинаем рассматривать фундаментальную модель сетевого взаимодействия - OSI
CSS анимация пульсации
8/31/2022Простой пример того, как реализовать анимацию пульсации, используя HTML и CSS
Для чего нужна ER-диаграмма в процессе разработки?
4/28/2023Обсудим в общих чертах, что такое ER-диаграмма и для чего она нужна.
От концепции к MVP
11/18/2022В этой статье вы узнаете, на примере, о том, как перейти от концепции к MVP без лишних усложнений в функционале продукта
Для чего нужны UML диаграммы?
5/23/2023В этой статье мы поговорим о том, что такое UML диаграммы, какие они бывают и где используются
Введение в написание технического задания
1/31/2023Техническое задание - это важная часть процесса разработки. В этой статье начнем погружение в данный вопрос.
Введение в разработку
10/10/2022Сегодня большинство компаний сталкивается с ИТ-разработкой и часто не получают то, чего хотят. В этой статье мы начинаем погружение в процесс создания ИТ-решений.
От идеи к концепции
10/27/2022В этой публикации мы поговорим о том, чем идея отличается от концепции. Сделаем это на примере конкретной цели
Методологии управления ИТ-проектами: Waterfall, Scrum, Prince2
11/27/2023В этой статье рассмотрим основные методологии управления ИТ-проектами.
Взвешенные графы
12/26/2022В этой статье мы познакомимся со взвешенными графами, алгоритмом Дейкстры и его реализацией на языке программирования Rust.
Процесс разработки: Планирование
8/16/2023В этой публикации мы начнем рассматривать процесс разработки. Начнем рассмотрение с процесса планирования.