Annotating Unstable Classes/Methods for Javadoc

Question

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.

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?

Answer 1

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

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 {
}

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

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