为Javadoc注释不稳定的类/方法 [英] Annotating Unstable Classes/Methods for Javadoc

问题描述

在为Java项目开发新的类/方法时，有时您想让人们试用您的新代码，但又不想保证它在将来的版本中将向后兼容.在这种情况下，使用@Unstable注释之类的东西来通知用户该代码在稳定之前将不具有向后兼容性保证(@Unstable功能与@Deprecated功能不同之处在于可以对其进行更改或删除)，这是有意义的.而不被视为重大更改).这些注释也必须反映在javadoc生成的HTML中，以便用户知道它们.非常乐观，如果您正在使用带注释的代码@Unstable，则出现编译器警告也将很有帮助.

When developing new classes/methods for a Java project, you sometimes want to let people try out your new code but don't want to guarantee it will be backwards-compatible in future versions. In this situation it would make sense to have something like an @Unstable annotation to notify users that this code will not have backwards compatibility guarantees until it stabilizes (an @Unstable feature is different from a @Deprecated feature in that it may be changed or removed without being considered a breaking change). It would also be necessary for such annotations to be reflected in the javadoc-generated HTML so that the user is aware of them. Being very optimistic, it would also be helpful for there to be a compiler warning if you are using code that is annotated @Unstable.

Java中是否有针对此类功能的标准?如果没有，是否可以自定义javadoc以允许此类功能?

Is there any standard for such a feature in Java? If not, is there a way to customize javadoc to allow for such a feature?

推荐答案

不，Java中没有针对此类功能的标准.

No, there is no standard for such a feature in Java.

要将这些信息添加到生成的Javadoc中，可以在自己的注释上使用@Documented.

To add this information to the generated Javadoc you can use @Documented on your own annotation.

import java.lang.annotation.Documented;

@Documented
public @interface Unstable {
}

使用此注释，注释将出现在带有注释的类型，字段，方法等的Javadoc中.

With this the annotation will appear in the Javadoc of the annotated type, field, method, etc.

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

这篇关于为Javadoc注释不稳定的类/方法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！