Javadocの「最初の文」

Javadocで生成されるドキュメントで、クラスやメソッドの概要に出力される「最初の文」はどのように決まるか。

Sunのマニュアルによると、

この「最初の文」は、直後にスペース、タブ、または改行が続く最初のピリオド (ロケールが英語に設定されている場合)、または最初のタグがある位置で終わります。
http://java.sun.com/javase/ja/6/docs/ja/technotes/tools/windows/javadoc.html

とあり、英語以外の場合がはっきり書いてない。ほかのところをよく見ると、どうやら英語以外のロケールではBreakIteratorクラスの行判別と同じらしいので、確認してみた。

↓こういうのを（UTF-8で）書いたとして、

package example;

/**
 * This is a test. Thank you.
 */
public class Test {
    /**
     * テストです。よろしく。
     */
    public static void main(String[] args) throws Exception {
    }
}

C:\workspace\test> javadoc -locale ja_JP -d doc -sourcepath src -subpackages example -encoding UTF-8

とすると、Testクラスのドキュメントの概要文は「This is a test.」になり、main メソッドのドキュメントの概要文は「テストです。」になる。「test.」の後のスペースは必要だけど、句点の後にスペースはいらないというのも BreakIteratorと同じ。

C:\workspace\test> javadoc -locale en_US -d doc -sourcepath src -subpackages example -encoding UTF-8

とすると、Testクラスのドキュメントの概要文は「This is a test.」のままだけど、main メソッドのドキュメントの概要文は「テストです。よろしく。」になる。句点の後にスペースがあっても無くても同じ。BreakIterator ならロケールが en_US でも句点で区切ってくれるけど、javadocのロケールが英語の場合、マニュアルの -breakiteratorオプションの項にあるような特別な方法で区切りが判定されるので、日本語の句点は対象外らしい。

ということで、javadocツールでは -locale オプションを常に指定して、どの環境でも同一の結果になるようにしたほうが良さそう。特に、日本語でドキュメンテーションコメントを書くなら -locale ja_JP を明示指定しないと環境によって出力が変わることがあり得る。