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

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

fn main() { // Строчные комментарии — это всё что угодно после '//' и до конца строки. let x = 5; // это тоже строчный комментарий. // Если у вас длинное объяснение для чего-либо, вы можете расположить строчные // комментарии один за другим. Поместите пробел между '//' и вашим комментарием, // так как это более читаемо. }

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

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

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

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

fn main() { /// Прибавляем единицу к заданному числу. /// /// # Examples /// /// ``` /// let five = 5; /// /// assert_eq!(6, add_one(5)); /// ``` fn add_one(x: i32) -> i32 { x + 1 } }

/// Прибавляем единицу к заданному числу.
///
/// # 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-комментариев, а так же запуска кода из примеров как тестов.