Java標準APIのソースコードの謎のjavadocタグ
なんとなくJavaのソースコードを調べていたら不思議なものを見つけた。
java.lang.ThreadクラスのisInterrupted()メソッドだ。
/** * Tests whether this thread has been interrupted. The <i>interrupted * status</i> of the thread is unaffected by this method. * * <p>A thread interruption ignored because a thread was not alive * at the time of the interrupt will be reflected by this method * returning false. * * @return <code>true</code> if this thread has been interrupted; * <code>false</code> otherwise. * @see #interrupted() * @revised 6.0 */ public boolean isInterrupted() { return isInterrupted(false); }
ここでjavadocコメントに使われている@revisedというタグ。javadocのドキュメントを見ても存在しない。また「今後のリリースで導入されるタグ」について書かれているというドキュメントを見てもやはり載っていない。
ちなみにreviseという単語は
[動](他)
reviseの意味 - goo辞書 英和和英
1 〈原稿・印刷物などを〉改訂［修正, 校訂, 校正］する
a revised edition
改訂版.
2 …を改める, 変える, 変更する
revise the constitution
憲法を改正する
revise one's daily schedule
日課を変更する
revise ... upwards ［downwards］
…を上方［下方］修正する.
3 (英)…を復習する.
といった具合だから、Java6.0で改定された、ぐらいの意味合いなのは想像がつく。
javadocを参照すると、
isInterrupted
public boolean isInterrupted()
このスレッドが割り込まれているどうかを調べます。このメソッドによってスレッドの「割り込みステータス」が影響を受けることはありません。
スレッドが割り込みの時点で生存していなかったために無視されたスレッドでの割り込みは、このメソッドによって反映されて false を返します。
戻り値:
Oracle Technology Network for Java Developers | Oracle Technology Network | Oracle
このスレッドが割り込まれている場合は true、そうでない場合は false
関連項目:
interrupted()
英語版は
isInterrupted
public boolean isInterrupted()
Tests whether this thread has been interrupted. The interrupted status of the thread is unaffected by this method.
A thread interruption ignored because a thread was not alive at the time of the interrupt will be reflected by this method returning false.
Returns:
Thread (Java Platform SE 6)
true if this thread has been interrupted; false otherwise.
See Also:
interrupted()
となっていて、@revised 6.0の記述はない。標準のドックレットでは@revisedというタグはjavadocドキュメントの生成に影響を与えないわけだから、妥当といえば妥当だ。
この由来不明、なぞの@revisedタグなのだが、Java6.0のソースコード*1を検索すると22箇所で使用されているのが分かる。
- java.net.DatagramSocket (3箇所)
- java.net.Socket (4箇所)
- java.net.ServerSocket (4箇所)
- java.lang.ClassLoader (1箇所)
- java.lang.Thread (3箇所)
- java.io.OutputStreamWriter (1箇所)
- java.io.FileOutputStream (1箇所)
- java.io.InputStreamReader (1箇所)
- java.io.FileInputStream (1箇所)
- java.io.RandomAccessFile (3箇所)
これらのソースの@authorタグはunascribedになっているから、具体的に誰が書いたかというのは分からないのだけど、中の人が個人的に使っていたカスタムドックレットなんじゃないかなぁという印象。
カスタムドックレットって何？
そもそも/** */形式のjavadocコメントを書いた後、JDK付属のjavadocツールを使うことでHTML形式のいわゆるjavadocドキュメントが生成されることを知らない人というのがそれなりにいる。
まあ、Eclipseとか使っているとHTMLに整形しなくとも、カーソルを合わせたりするだけで参照できるから不便はないわけだけどもね。
この時、標準の生成ツール―これをドックレットと呼ぶ―を使うとJavaの標準APIのjavadocでおなじみのjavadocドキュメントが生成される。
しかし、この生成されるドキュメントをカスタマイズしたいという要求もあるだろう。この時、独自のカスタムドックレットを作り、javadocコマンドに渡してやることで独自のドキュメント生成が可能となる。業務上必要な追加項目とかあるならカスタムしてみるのもいいんじゃないかな。
ドックレットについての概要は公式のドキュメントが詳しい。
結構古いがJava Developer Connection テクニカルティップも参考になる。
