<НазадДокументирование кода в языке программирования 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. Более подробно про документирование можно почитать здесь.
Самое свежее
Простыми словами о графах
12/18/2022В этой статье мы начнем знакомство с графами, познакомимся с одним из алгоритмов для работы с графами и реализуем граф на языке программирования Rust.
В чем отличие аутсорсинга разработки от аутстаффинга ИТ-сотрудника для разработки?
10/17/2022В этой статье разберемся, что такое аутсорс- и аутстафф-разработка.
UI/UX дизайн: Процесс создания
4/9/2023В этой статье поговорим об основных шагах в процессе создания UI/UX дизайна.
UI/UX дизайн: Введение
3/29/2023В этой статье мы начинаем знакомиться с UI/UX дизайном. Это важнейший этап в разработке любого визуального интерфейса приложений.
Знакомьтесь, Пентест
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В этой публикации мы поговорим о том, чем идея отличается от концепции. Сделаем это на примере конкретной цели
Взвешенные графы
12/26/2022В этой статье мы познакомимся со взвешенными графами, алгоритмом Дейкстры и его реализацией на языке программирования Rust.
Зачем VPN бизнесу?
9/27/2022В этой статье мы рассмотрим то, как можно обезопасить доступ к облачным ресурсам предприятия с помощью VPN