web-dev-qa-db-ja.com

@deprecatedのような実験的または不完全なAPIを文書化する方法は?

メソッドまたはAPIがコードベースにあるが、実装が完全でないか変更される可能性があるため使用しないことを意味する「非推奨」と同様であるが異なる適切な用語はありますか? (そうですね、これらのメソッドは公開すべきではありません。yadayada yada。自分の状況を作り出したのではなく、それを最大限に活用しようとしているだけです。)

人々は何を示唆していますか?実験的、不完全、他に何か?

まだ流動的なこのAPIのjavadocドキュメントを作成している場合、@ deprecatedタグを使用する必要がありますか、それともより良い規則がありますか?私にとって@deprecatedは、このAPIが古く、新しい優先メカニズムが利用可能であることを意味します。私の状況では、代替手段はありませんが、APIの一部のメソッドは完了していないため、使用しないでください。この時点では、それらを非公開にすることはできませんが、ドキュメントに明確な警告を入れたいと思います。

12
Michael Levy

適切な用語はおそらくincubatorで、これはGoogleとApacheで使用されているものです。

  • google-web-toolkit-incubator

    Google Web Toolkitのウィジェットとライブラリの公式インキュベーター...

  • Apacheインキュベーター

    ...完全に本格的なApache Software Foundationプロジェクトになることを目的としたオープンソースプロジェクトのゲートウェイ...

上記のプロジェクトをよく見ると、「実験的な」API(GWTなど)には、com.google.gwt.gen2のような「専用の」パッケージ名が付いている傾向があります。これは、永続的な公共の消費を目的とした将来の「最終化された」APIを汚染しないようにするためです。

「ダイヤモンドのような公開APIは永久に存在します。正しく取得するチャンスが1回あるので、最善を尽くしてください...」(Joshua Bloch、- 優れたAPIを設計する方法と重要な理由

8
gnat

純粋に実用的な理由で@deprecatedを使用します。

@deprecatedは、希望する正確な意味を伝えていませんが、重要な利点があります:Javaコンパイラには組み込みのサポートがあります。-deprecationフラグを使用したコンパイル非推奨のメソッドをオーバーライドするすべての場所を見つけることができるため、ユーザーは不審なコードをすばやく見つけることができます。@deprecated Javadocタグを使用すると、ドキュメントを読みたい人に実際に何が起こっているのかを説明できます。 APIは試験的なものであり、自己の責任において使用する必要があることなどをユーザーに伝えることができます。

10
dasblinkenlight

実験的な機能や不完全な機能はパブリックAPIでは何もしないため、他のAPIでこのようなものを見たことはありません。

選択肢がないため、APIの一部が変更される可能性があることを明確に示す警告を表示します。

3