1. 概要

Javadoc は、JavaソースコードからHTML形式のドキュメントを生成する方法です。

このチュートリアルでは、ドキュメントコメントの@versionタグと@sinceタグに焦点を当てます。

2. @versionおよび@sinceの使用法

このセクションでは、@versionおよび@sinceタグを適切に使用する方法について説明します。

2.1. @version

@versionタグの形式は簡単です。

@version  version-text

たとえば、これを使用してJDK1.7を示すことができます。

/**
 * @version JDK 1.7
 */

@version タグを使用する場合、2つの異なる使用シナリオがあります。

  • 単一のファイルのバージョンを記録する
  • ソフトウェア全体のバージョンをマークする

明らかに、これら2つのシナリオの間に矛盾があることがわかります。 これは、単一のファイルのバージョンがソフトウェアのバージョンと互換性がない可能性があるためです。 また、ファイルが異なればファイルバージョンも異なる場合があります。 では、 @version タグをどのように使用する必要がありますか？

以前、Sunは@versionタグを使用して単一ファイルのバージョンを記録していました。また、@versionタグでSCCS文字列「%I」を使用することをお勧めします。 %、%G%“。 次に、SCCSは、「 %I % 」を現在のバージョンのファイルに置き換え、「 %G%」を日付「mm/dd/」に置き換えます。 yy」ファイルをチェックアウトするとき。 たとえば、「1.39、02 / 28/97」（mm / dd / yy）のようになります。  さらに、％I％は、ファイルを編集および削除（デルタ+取得）するたびに増分されます。

SCCSは、ソースコード制御システムとも呼ばれます。 SCCSコマンドについて詳しく知りたい場合は、こちらを参照してください。 さらに、SCCSは昔ながらのソースコードバージョン管理システムです。

現在、ソフトウェア全体のバージョンを示すために@versionタグを使用する傾向があります。 これに照らして、それは @バージョン不必要に単一のファイルに配置されたタグ。

単一のファイルのバージョンが重要でなくなったことを意味しますか？ それは実際には真実ではありません。 現在、Git、SVN、CVSなどのバージョン管理ソフトウェアが最新化されています。 各バージョン管理ソフトウェアには、すべてのファイルのバージョンを記録する独自の方法があり、@versionタグに依存する必要はありません。

例としてOracleJDK8を取り上げましょう。 src.zip ファイルのソースコードを見ると、java.awt.Colorクラスに@versionタグがあるだけであることがわかります。

/**
 * @version     10 Feb 1997
 */

したがって、 @version タグを使用して、単一ファイルのバージョンがフェードしていることを示していると推測できます。 したがって、 Oracle doc は、@versionタグを使用してソフトウェアの現在のバージョン番号を記録することを提案しています。

2.2. @since

@sinceタグの形式は非常に単純です。

@since  since-text

たとえば、これを使用して、JDK1.7で導入された機能をマークできます。

/**
 * @since JDK 1.7
 */

つまり、 @sinceタグを使用して、変更または機能が最初に存在した時期を記述します。同様に、単一のファイルのバージョンではなく、ソフトウェア全体のリリースバージョンを使用します。 Oracle doc には、@sinceタグの使用方法に関する詳細な手順が記載されています。

  • 新しいパッケージを導入するときは、パッケージの説明とその各クラスで@sinceタグを指定する必要があります。
  • 新しいクラスまたはインターフェイスを追加するときは、クラスメンバーの説明ではなく、クラスの説明に1つの@sinceタグを指定する必要があります。
  • 既存のクラスに新しいメンバーを追加する場合は、クラスの説明ではなく、新しく追加されたメンバーにのみ@sinceタグを指定する必要があります。
  • 今後のリリースでクラスメンバーをprotectedからpublicに変更する場合、@sinceタグを変更しないでください。

@since タグは、ソフトウェアユーザーが特定のリリースバージョンの後でのみ特定の機能を期待する必要があるという重要なヒントを提供するため、かなり重要な場合があります。

src.zip ファイルをもう一度見ると、@sinceタグの使用法がたくさんあることがわかります。 例としてjava.lang.FunctionalInterfaceクラスを取り上げましょう。

/**
 * @since 1.8
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface FunctionalInterface {}

このコードスニペットから、FunctionalInterfaceクラスはJDK8以降でのみ使用可能であることがわかります。

3. @versionと@sinceの類似点

このセクションでは、@versionタグと@sinceタグの類似点を見てみましょう。

3.1. 両方ともブロックタグに属します

まず、@versionと@sinceの両方がブロックタグに属しています。

ドキュメントコメントでは、タグは2つのタイプに分類できます。

  • タグをブロックする
  • インラインタグ

ブロックタグの形式は@tagです。 また、先頭のアスタリスク、空白、および区切り文字（ / ** ）を無視して、行の先頭に表示する必要があります。 たとえば、タグセクションで@versionと@sinceを使用できます。

/**
 * Some description here.
 * 
 * @version 1.2
 * @since 1.1
 */

ただし、インラインタグの形式は {@tag}です。 また、説明やコメントのどこにでも存在できます。 たとえば、 {@ link} タグがある場合、それを説明で使用できます。

/**
 * We can use a {@link java.lang.StringBuilder} class here.
 */

3.2. 両方とも複数回使用できます

次に、@ versionと@sinceの両方を複数回使用できます。最初は、この使用法にショックを受ける可能性があります。 次に、@versionタグが1つのクラスに複数回表示されるのはなぜだろうと思うかもしれません。 しかし、それは真実であり、ここに文書化されています。 また、複数のAPIで同じプログラム要素を使用できることを説明しています。 したがって、同じプログラム要素でさまざまなバージョンをアタッチできます。

たとえば、ADKとJDKの異なるバージョンで同じクラスまたはインターフェイスを使用する場合、異なる@versionおよび@sinceメッセージを提供できます。

/**
 * Some description here.
 *
 * @version ADK 1.6
 * @version JDK 1.7
 * @since ADK 1.3
 * @since JDK 1.4
 */

生成されたHTMLページで、Javadocツールは名前の間にコンマ（、）とスペースを挿入します。 したがって、バージョンテキストは次のようになります。

ADK 1.6, JDK 1.7

そして、以来のテキストは次のようになります。

ADK 1.3, JDK 1.4

4. @versionと@sinceの違い

このセクションでは、@versionタグと@sinceタグの違いを見てみましょう。

4.1. コンテンツが変わるかどうか

@versionテキストは絶えず変化しており、@ sinceテキストは安定しています。時間が経つにつれて、ソフトウェアは絶えず進化しています。 新機能が加わりますので、バージョンは変わり続けます。 ただし、 @since タグは、新しい変更または機能が発生した過去の時点のみを識別します。

4.2. それらを使用できる場所

これらの2つのタグの使用法は少し異なります。

  • @version ：概要、パッケージ、クラス、インターフェース
  • @since ：概要、パッケージ、クラス、インターフェース、フィールド、コンストラクター、メソッド

@sinceタグは使用範囲が広く、すべてのドキュメントコメントで有効です。 対照的に、 @version タグは使用範囲が狭く、フィールド、コンストラクター、またはメソッドで使用することはできません。

4.3. デフォルトで表示されるかどうか

これらの2つのタグは、デフォルトで生成されたHTMLページで異なる動作をします。

  • @versionテキストはデフォルトでは表示されません
  • @sinceテキストはデフォルトで表示されます

生成されたドキュメントにに「バージョンテキスト」を含めたい場合は、-versionオプションを使用できます。

javadoc -version -d docs/ src/*.java

同様に、生成されたドキュメントで「テキスト以降」を省略したい場合は、-nosinceオプションを使用できます。

javadoc -nosince -d docs/ src/*.java

5. 結論

このチュートリアルでは、最初に@versionタグと@sinceタグを正しく使用する方法について説明しました。 次に、それらの類似点と相違点について説明しました。 つまり、 @version タグはソフトウェアの現在のバージョン番号を保持し、@sinceタグは変更または機能が最初に存在した時期を示します。