キーワードを挙げ、トピックへの道しるべを示す

// 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 {
    /// スキーマと、その後に続く有効なデータフィールドの集合を決定します。  
    ///
    /// リーダーの byte 6 にエンコードされています。  
    pub type_of_record: char,

    /// より大きな著作物内の記事に対する "773 Host  
    /// Item Entry" のような関連フィールドをパースするかどうかを示します。  
    ///  
    /// リーダーの byte 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 comment の大半を精読するわけではありません。

    ユーザーはたいてい、その場で解決しようとしている問題に関係する ドキュメントの箇所を見つけるために、ざっと読み、拾い読みします。

    自分に関係のあるキーワードや、道しるべになりそうな語を見つけると、 ユーザーは文書化されている対象の前後の文脈を探し始めます。

  • クラスに質問: ドキュメントでは何を探しますか? ここでは、一般的に ドキュメントに求める価値ではなく、その場その場の情報探索に注目してください。

  • キーワードは段落のなるべく冒頭で挙げる。

    これはざっと読むことや拾い読みの助けになります。段落の最初の数語が 最も目に入りやすいからです。

    ざっと読むことや拾い読みは、ユーザーがテキスト内を素早く移動する助けに なります。キーワードをできるだけ段落の冒頭近くに置くことで、関連情報 を見つけたかどうかをより早く判断できます。

  • 道しるべは示す。ただし説明しすぎない。

    ユーザーが API 設計者と同じドメイン知識を持っているとは限りません。

    本筋ではない専門用語や頭字語に触れる場合は、初心者がすぐに追加で 調べられるだけの十分な文脈を持ち込むようにしてください。

  • 道しるべの提示は自然に起こることもよくあります。たとえば、さまざまな プロトコルに言及するネットワーキングライブラリを考えてみてください。 しかし、自然にそうならない場合は、何に触れるべきかを選ぶのが難しく なります。

    経験則: API 開発者は「初心者が自分の文書化しているものに出会ったら、 どの情報源を調べるだろうか。また、紛らわしい誤った手がかりを追って しまう可能性はあるだろうか」と自問すべきです。

    ユーザーには、自分で主題を調べられるだけの十分な情報を与えるべきです。

  • すでに扱った、命名規則を含む API の予測可能性も、道しるべの一形態です。