54

クラスの一部として@versionとの両方を含める理由はありますか?@since

それらは相互に排他的であるようです。

また、とは何%I%を%G% 意味し、どのように設定/使用するのですか?

 @version %I%, %G%
4

4 に答える 4

76

タグは、問題のリリースまたはファイルの@version現在のバージョンである必要があります。,構文は%I%、%G%ソース管理ソフトウェアがファイルの現在のバージョンとファイルがチェックアウトされた日付に置き換えるマクロです。

この@sinceタグは、メソッドやクラスなどを追加したバージョンを定義するために使用する必要があります。これは、パッケージの特定のバージョンに対して実行する場合にのみメソッドを期待する必要があるという他の開発者へのヒントです。他の誰かが使用することを意図したライブラリとしてコードを出荷している場合、ドキュメントのこれらの非常に重要な部分を検討します。

于 2009-02-23T16:55:22.353 に答える
17

Oracle の記事How to Write Doc Comments for the Javadoc Tool で詳しく説明されています。

@version

…クラスとインターフェースのみ。

Java Software では、SCCS のバージョンに @version を使用しています。詳細については、「man sccs-get」を参照してください。コンセンサスは次のようです。

%I% は、ファイルを編集および削除するたびに増加します

%G% は日付 mm/dd/yy

ファイルを作成すると、%I% は 1.1 に設定されます。編集して削除すると、1.2 に増加します。

一部の開発者は、日付 %G% が紛らわしい場合は省略します (そして、省略しています)。たとえば、%G% が 3 月 4 日に生成する 3/4/96 は、米国外の人々によって解釈されます。 4月3日を意味する州。一部の開発者は、(1 日に複数回チェックインするため) より細かい解決が必要な場合にのみ、時間 %U% を含めます。

最も明確な数値日付形式は、ISO 8601 などで提案されているように、yyyy-mm-dd のように最初に年を付けて日付をフォーマットすることです ( http://www.cl.cam.ac.uk/~など)。 mgk25/iso-time.html )、しかしその拡張は SCCS から来る必要があります。

@since

Java名がAPI仕様に追加されたときの製品バージョンを指定します（実装と異なる場合）。たとえば、バージョン 1.2 の Java 2 Platform, Standard Edition, API Specification にパッケージ、クラス、インターフェース、またはメンバーが追加された場合は、次を使用します。

/**
 * @since 1.2
 */

Javadoc 標準ドックレットは、文字列引数をテキストとして持つ「Since」小見出しを表示します。この小見出しは、ソース doc コメント内の @since タグが表示される場所に対応する場所にのみ、生成されたテキストに表示されます (Javadoc ツールは、階層の下に増殖しません)。

(かつては "@since JDK1.2" という慣習がありましたが、これは Java プラットフォームの仕様であり、Oracle JDK や SDK に固有のものではないため、"JDK" を削除しました。)

パッケージを導入するときは、そのパッケージの説明とその各クラスに @since タグを指定します。(各クラスに @since タグを追加することは技術的には必要ありませんが、ソース コードの可視性を高めるため、私たちの規則です。) オーバーライド タグがない場合、@since タグの値はパッケージの各クラスに適用され、メンバー。

クラス (またはインターフェース) を導入するときは、クラスの説明に @since タグを 1 つ指定し、メンバーには @since タグを指定しないでください。クラスより新しいバージョンで追加されたメンバーにのみ @since タグを追加します。これにより、@since タグの数が最小限に抑えられます。

後のリリースでメンバーが protected から public に変更された場合、@since タグは、サブクラスだけでなく、すべての呼び出し元が使用できるようになったとしても、変更されません。

于 2015-08-27T10:00:05.480 に答える
8

それらがどのように相互に排他的であるかはわかりません。1 つはバージョンを定義するために使用され、もう 1 つはメソッドがいつから存在するかを記述するために使用されます。例えば：

/**
 * Does Whatever
 * @version 1.2.3
 * @since 1.2.0
 *
 */
public void myMethod() {
    // .......
}

あなたが言及したキャラクターに関しては、それらは独自のもののようであり、いずれにせよ、私はそれらが何を意味するのか見当がつきません.

于 2009-02-23T16:54:16.067 に答える
2

@version編集ごとに記録されます。 [1.3.21]

@since[1.3] Yuval Adam は興味深いですが、これは標準ではありません。java doc の目的は、誰もが理解できるようにすることです。

于 2012-07-13T02:59:26.630 に答える