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

【问题标题】：Annotating Unstable Classes/Methods for Javadoc为 Javadoc 注释不稳定的类/方法
【发布时间】：2015-09-13 23:42:38
【问题描述】：

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

在 Java 中有这样一个特性的标准吗？如果没有，有没有办法自定义 javadoc 以允许这样的功能？

【问题讨论】：

unstable 和 deprecated 有什么区别？我不知道一个标准。您可以创建自己的注释。
@emory Deprecated 适用于应逐步淘汰的旧代码，unstable 适用于处于 beta 状态的新代码。在项目有一个主要版本增量之前，通常仍然支持已弃用的代码，但不稳定的代码可能随时更改。
其实deprecated的字典定义是“强烈反对； 在计算中：计划逐步淘汰，但仍可供使用”。如果您查看@Deprecated 的官方文档，它们似乎使用通用定义而不是特定于计算的定义。 OTOH，我问了一个类似的问题（标记不稳定的功能是否是@Deprecated 的预期用例），并且建议我不要以这种方式使用它。

标签： java javadoc

【解决方案1】：

不，Java 中没有此类功能的标准。

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

import java.lang.annotation.Documented;

@Documented
public @interface Unstable {
}

这样，注解就会出现在被注解的类型、字段、方法等的Javadoc中

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

【讨论】：