如何记录实验性或不完整的API，例如@deprecated？

是否有一个与“不赞成使用”相似但又不同的好术语，表示方法或API已存在于代码库中，但由于其实现不完整或可能会发生变化而不应使用？（是的，我知道，这些方法不应该公开，yada yada yada。我没有创造自己的情况，我只是想尽力而为。）

人们有什么建议？实验性的，不完整的，还有其他吗？

如果我正在为该API构建仍在不断变化的javadoc文档，那么我应该使用@deprecated标记还是有更好的约定？对我而言，@ preprecated表示此API很旧，可以使用更新的首选机制。在我的情况下，别无选择，但是API中的某些方法尚未完成，因此不应使用。目前，我无法将其设为私有，但我想在文档中添加明确的警告。

合适的术语最有可能是孵化器，这是Google和Apache使用的术语：

• google-web-toolkit-incubator

  Google Web Toolkit的小部件和库的官方孵化器...

• 阿帕奇孵化器

  旨在成为成熟的Apache Software Foundation项目的开源项目的网关...

如果仔细看一下上面提到的项目，您可能会注意到“实验性” API（例如在GWT中）倾向于具有“专用”包名称，例如com.google.gwt.gen2。这是为了避免污染将来用于永久公众消费的“最终” API-因为您知道，

“像钻石一样，公共API永远存在。您有机会把它弄对，所以请尽力而为...”（Joshua Bloch，《如何设计一个好的API及其重要性》）

我@deprecated纯粹出于实际原因会使用。

尽管@deprecated没有传达您想要的确切含义，但是它具有显着的优势：Java编译器对此具有内置支持。使用-deprecationflag进行编译可让您找到覆盖不推荐使用的方法的所有位置，从而帮助您的用户快速找到可疑代码。您可以使用@deprecatedJavadoc标记向所有希望阅读您的文档的人解释真正的情况。在这里，您可以告诉用户API是实验性的，应自行承担风险，依此类推。

我从未在其他API中看到过类似的东西，因为实验性或不完整的功能与公共API无关。

由于您别无选择，只需发出清晰可见的警告，即API的一部分可能会更改。