<Назад

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

Всем привет! 🖖

В этой статье я расскажу об основных моментах документирования кода в 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. Более подробно про документирование можно почитать здесь.