概要
Javadoc を生成したとき、サマリーの「説明」欄がどのように決まるのかを調べた。
「説明」欄に記載される「最初の文」の区切りは Javadoc 生成時のロケールに依存する。
英語ロケールではピリオド .、日本語ロケールでは 。 が最初に出現するまで、または最初の p や pre の開始タグの直前までである。
サマリーと詳細
javadoc コマンドで生成される HTML ページは、まず各項目のサマリー1を記載し、その後に各項目の詳細が続く形式をとる。サマリーの「説明」に記載されるのが Javadoc コメントの「最初の文」である。
「最初の文」に続く下図下線部は、詳細にのみ記載される。
ロケールが英語のとき
English default sentence-break algorithm — Stops at a period followed by a space or an HTML block tag, such as <P>.
javadoc -breakiterator
例えば -locale en_US を指定すると、ピリオド . にスペースや改行が続いたとき、ピリオドまでが「最初の文」となる。
以下の例では hello. が「最初の文」である。
hello. world
hello.[TAB]world
hello.
world
以下の例の hello. では、「最初の文」は区切られない。
hello.world
hello.<br>world
hello.<div>world</div>
冒頭に引用したドキュメントによれば、ピリオドに HTML ブロックタグが続いたとき「最初の文」として扱うとされているが、div タグはそのように扱われなかった。
一方、 p や pre タグがあらわれると、直前にピリオドがなくても直前までが「最初の文」になるようだ。
以下の例の hello は「最初の文」である。
hello<p>world
hello<pre>world</pre>
なお、ロケールが英語のときに -breakiterator オプションを有効化すると、「最初の文」を別のアルゴリズムで区切るようになるが、本稿では割愛する。
ロケールが日本語のとき
ロケールが英語ではないとき、BreakIterator クラス によって検出される「最初の文」が採用される。
日本語の場合、すなわち -locale ja_jp を指定すると、句点 。 が行の区切りとなる。2
以下の例では こんにちは。 が「最初の文」である。
こんにちは。日本。
こんにちは。
日本。
以下の例の こんにちは では、「最初の文」は区切られない。
こんにちは<br>日本。
こんにちは<div>日本。</div>
英語と同様に、 p や pre タグがあらわれると、直前に句点がなくても直前までが「最初の文」になる。
以下の例の こんにちは は「最初の文」である。
こんにちは<p>日本。
こんにちは<pre>日本。</pre>
詳細は <p> に続けて書く
ドキュメントの言語にあったロケールを指定して javadoc コマンドを実行する限り、上記のルールに従って分割される。しかし、例えば IDE などで正しいロケールを認識しない場合もあるかもしれない。3
典型的には、日本語の Javadoc が -locale en_US で生成された場合、ほとんどの文ではピリオド . が出現しないため、全文がサマリーに出力されてしまう。
そこで、以下のような方針をとると、概ねロケールに依存せずに「最初の文」を区別できる。
- 「最初の文」は、途中にピリオド
.や句点。を含まないように書き、末尾にはドキュメントの言語にあった句点をつける（例えば、英語なら.、日本語なら。） - 詳細は
<p>に続けて書く
サマリーはひとつの文で、簡潔に書く。
<p>詳細は、次の段落に分けて記載する。
なお、p の閉じタグ </p> は省略できる。
特徴的なのは
</p>で閉じる前に他のブロックレベル要素が見つかった場合は自動的に閉じることです。
<p>: 段落要素 - HTML: HyperText Markup Language | MDN
-
手元で
javadocコマンドを実行すると「サマリー」ではなく「概要」と翻訳された。訳語の差異は本題ではないので、本稿では JDK の Javadoc における訳語を採用する。 ↩ -
BreakIterator#getSentenceInstance による境界を採用しているとみられる。該当の実装はおそらくここ。 ↩
-
実際にこれが問題になる環境がどれほどあるのかはともかく、期待した結果の得られる確率を高める作法は知っておいて損はないと思う。 ↩