Упоминание ключевых слов и навигация по темам

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

/// Разобранное представление [заголовка записи MARC 21][leader].
///
/// Заголовок MARC содержит метаданные, которые определяют, как интерпретировать остальную часть
/// записи.
///
/// [leader]: https://www.loc.gov/marc/bibliographic/bdleader.html
pub struct Leader {
    /// Определяет схему и набор допустимых последующих полей данных.
    ///
    /// Кодируется в байте 6 заголовка.  
    pub type_of_record: char,

    /// Указывает, нужно ли разбирать поля связей, например «773 Host
    /// Item Entry» для статьи внутри более крупного труда.
    ///
    /// Кодируется в байте 7 заголовка.  
    pub bibliographic_level: char,
    // ... остальные поля
}

/// Разбирает [заголовок записи MARC 21][leader].
///
/// Заголовок кодируется как поле фиксированной длины в 24 байта, содержащее метаданные,
/// которые определяют семантическую интерпретацию остальной части записи.
///
/// [leader]: https://www.loc.gov/marc/bibliographic/bdleader.html
pub fn parse_leader(leader_bytes: &[u8; 24]) -> Result<Leader, MarcError> {
    todo!()
}

#[derive(Debug)]
pub enum MarcError {}

Мотивация: читатели документации не будут внимательно читать большинство ваших doc-комментариев так, как читают диалоги в любимом романе.

Пользователи, скорее всего, будут бегло просматривать текст и искать часть документации, относящуюся к проблеме, которую они решают в данный момент.

Как только пользователь найдёт ключевое слово или возможный указатель, который ему нужен, он начнёт искать контекст вокруг описываемого.
Спросите класс: что вы ищете в документации? Сосредоточьтесь здесь на поиске информации в данный момент, а не на общих ценностях документации.
Называйте ключевые слова ближе к началу абзаца.

Это помогает при беглом просмотре, так как первые несколько слов абзаца выделяются больше всего.

Просмотр и сканирование позволяют пользователям быстро перемещаться по тексту. Если ключевые слова стоят как можно ближе к началу абзаца, пользователь быстрее определит, нашёл ли он нужную информацию.
Указывайте направление, но не объясняйте слишком подробно.

У пользователей не обязательно будет такая же экспертиза в предметной области, как у разработчика API.

Если упоминается побочный, специализированный термин или аббревиатура, постарайтесь привести достаточно контекста, чтобы новичок мог быстро провести дополнительное исследование.
Указание направления часто происходит естественно: например, библиотека для работы с сетью может упоминать различные протоколы. Но когда этого не происходит естественно, может быть трудно выбрать, что упомянуть.

Практическое правило: разработчики API должны спрашивать себя: «Если новичок столкнётся с тем, что я документирую, какие источники он найдёт и есть ли там ложные следы, по которым он может пойти?»

Пользователям следует давать достаточно информации, чтобы они могли самостоятельно искать темы.
То, что мы уже рассмотрели — предсказуемость API, включая соглашения об именовании, — тоже является формой указания направления.

Keyboard shortcuts

Comprehensive Rust 🦀

Упоминание ключевых слов и навигация по темам