Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Устройство doc-комментария

  1. Краткое резюме в одно предложение.
  2. Более подробное объяснение.
  3. Специальные разделы: примеры кода, паники, ошибки, предусловия безопасности.
// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Разбирает пару «ключ-значение» из строки.
///
/// Входная строка должна быть в формате `key=value`. Всё до первого
/// '=' считается ключом, а всё после --- значением.
///
/// # Examples
///
/// ```
/// use my_crate::parse_key_value;
/// let (key, value) = parse_key_value("lang=rust").unwrap();
/// assert_eq!(key, "lang");
/// assert_eq!(value, "rust");
/// ```
///
/// # Panics
///
/// Вызывает панику, если входная строка пуста.
///
/// # Errors
///
/// Возвращает `ParseError::Malformed`, если строка не содержит `=`.
///
/// # Safety
///
/// Вызывает неопределённое поведение, если...
unsafe fn parse_key_value(s: &str) -> Result<(String, String), ParseError>

enum ParseError {
    Empty,
    Malformed,
}

  • Идиоматичные doc-комментарии Rust следуют общепринятой структуре, которая облегчает их чтение разработчиками.

  • Первая строка doc-комментария — однопредложное резюме функции. Делайте её краткой. rustdoc и другие инструменты строго ожидают этого: её используют как краткое описание в документации модуля и в результатах поиска.

  • Далее можно дать длинное, многоабзацное описание «зачем» и «что» делает функция. Используйте Markdown.

  • Наконец, можно использовать заголовки разделов верхнего уровня, чтобы организовать содержимое. В doc-комментариях обычно используются # Examples, # Panics, # Errors и # Safety как заголовки разделов. Сообщество Rust ожидает видеть в этих разделах описание релевантных аспектов вашего API.

  • Rust сильно ориентирован на безопасность и корректность. Документирование поведения вашего кода в случае ошибок имеет решающее значение для написания надёжного ПО.

  • # Panics: если ваша функция может вызвать панику, вы должны задокументировать конкретные условия, при которых это может произойти. Вызывающему коду нужно знать, чего избегать.

    • Вопрос: спросите класс, почему документирование паник так важно в языке, который предпочитает возвращать Result.

    • Ответ: паники предназначены для неисправимых ошибок программирования. Библиотека не должна паниковать, если только вызывающий код не нарушил контракт. Документирование этих контрактов необходимо.

  • # Errors: для функций, возвращающих Result, этот раздел объясняет, какие виды ошибок могут возникнуть и при каких обстоятельствах. Вызывающему коду эта информация нужна, чтобы писать надёжную логику обработки ошибок.

  • Комментарии # Safety документируют предусловия безопасности для небезопасных функций, которые должны выполняться, иначе может возникнуть неопределённое поведение. Подробно они рассматриваются в углублённом курсе по небезопасному Rust.