为Javadoc注释不稳定的类/方法

在为Java项目开发新的类/方法时，您有时希望让人们试用您的新代码，但不希望保证它在将来的版本中向后兼容。在这种情况下，使用@Unstable注释之类的东西来通知用户，此代码在稳定之前不会有向后兼容性保证是有意义的（@Unstable特性不同于@Deprecated特性，因为它可能会被更改或删除，而不会被视为破坏性更改）。还需要将这些注释反映在javadoc生成的HTML中，以便用户知道它们。非常乐观的是，如果您正在使用注释为@Unstable的代码，那么出现编译器警告也会很有帮助

---

在Java中有这样一个特性的标准吗？如果没有，有没有办法定制javadoc来支持这样一个功能？

没有，Java中没有这样一个功能的标准

要将此信息添加到生成的Javadoc中，您可以在自己的注释中使用

@Documented

import java.lang.annotation.Documented;

@Documented
public @interface Unstable {
}

这样，注释将出现在Javadoc中，包含注释类型、字段、方法等

public interface AlwaysChangingApi {
    @Unstable
    String process(String someParameter);
}

---

不稳定和不推荐有什么区别？我不知道有什么标准。您可以创建自己的批注。@emory不推荐用于应逐步淘汰的旧代码，不稳定用于处于测试状态的新代码。不推荐使用的代码通常会一直受到支持，直到项目有一个主要的版本增量，但不稳定的代码可能会在任何时候被更改。实际上，字典对不推荐使用的代码的定义是“强烈反对；在计算中：计划逐步淘汰，但仍然可以使用”。如果你查看官方文档中的

@弃用的
，它们似乎与通用定义一致，而不是特定于计算的定义。OTOH，我问了一个类似的问题（标记不稳定的特性是否是
@Deprecated
的预期用例），以及我收到的反对以这种方式使用它的意见。