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

メソッドまたはAPIがコードベースにあるが、実装が完全ではないか、変更される可能性が高いため、使用すべきではないという意味で、「非推奨」と似ているが異なる用語はありますか？（ええ、私は知っています、これらの方法は公開すべきではありません、やだやだやだ。自分の状況を作り出したのではなく、それを最大限に活用しようとしています。）

人々は何を提案しますか？実験的、不完全、他の何か？

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

適切な用語はインキュベーターである可能性が最も高く、これはGoogleとApacheで使用される用語です。

• google-web-toolkit-incubator

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

• Apacheインキュベーター

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

上記のプロジェクトを詳しく見ると、「実験的な」API（例：GWT）には「専用」のパッケージ名が付いていることがわかりますcom.google.gwt.gen2。これは、永続的な公共消費を目的とした将来の「最終的な」APIの汚染を避けるためです。

「ダイヤモンドのようなパブリックAPIは永遠に存在します。それを正しく実現するチャンスがあるので、ベストを尽くしてください...」（Joshua Bloch、優れたAPIの設計方法と重要性）

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

けれども@deprecatedあなたが好きだろうと正確な意味を伝えていない、それは重要な利点があります：Javaコンパイラが組み込まれている、それをサポートしています。-deprecationフラグ付きでコンパイルすると、非推奨のメソッドをオーバーライドするすべての場所を見つけることができ、ユーザーが疑わしいコードを非常に迅速に見つけるのに役立ちます。@deprecatedJavadocタグを使用して、ドキュメントを読みたい人に実際に何が起こっているのかを説明できます。これは、APIが実験的であり、独自のリスクで使用する必要があることなどをユーザーに伝えることができる場所です。

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

選択の余地がないため、APIの一部が変更される可能性があることを明確に警告するだけでかまいません。