% Комментарии

Теперь, когда у нас есть несколько функций, неплохо бы узнать о комментариях. Комментарии — это заметки, которые вы оставляете для других программистов, чтобы помочь объяснить некоторые вещи в вашем коде. Компилятор в основном игнорирует их («в основном», потому что есть документирующие комментарии и примеры в документации).

В Rust есть два вида комментариев: строчные комментарии и doc-комментарии.

// Строчные комментарии — это всё что угодно после '//' и до конца строки.

let x = 5; // это тоже строчный комментарий.

// Если у вас длинное объяснение для чего-либо, вы можете расположить строчные
// комментарии один за другим. Поместите пробел между '//' и вашим комментарием,
// так как это более читаемо.

Другое применение комментария — это doc-комментарий. Doc-комментарий использует /// вместо //, и поддерживает Markdown-разметку внутри:

/// Прибавляем единицу к заданному числу.
///
/// # Examples
///
///

/// let five = 5; /// /// assert_eq!(6, add_one(5)); /// fn add_one(x: i32) -> i32 { x + 1 }

При написании doc-комментария очень полезно добавлять разделы для аргументов, возвращаемых значений и привести некоторые примеры использования. Заметьте, что здесь мы использовали новый макрос: assert_eq!. Он сравнивает два значения и вызывает panic!, если они не равны. Для документации такие примеры очень полезны. Так же есть и другой макрос, assert!, который вызывает panic! когда значение равно false.

Вы можете использовать rustdoc для генерации HTML- документации из этих doc-комментариев, а так же запуска кода из примеров как тестов.