7

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?

Iceberg
  • 376
  • 1
  • 12
  • 1
    What is the difference between unstable and deprecated? I am not aware of a standard. You can just create your own annotation. – emory Sep 13 '15 at 23:46
  • 1
    @emory Deprecated is intended for old code that should be phased out, unstable is intended for new code in a beta state. Deprecated code is usually still supported until the project has a major version increment, but unstable code may be changed at any time. – Iceberg Sep 14 '15 at 00:04
  • Actually, the dictionary definiton of *deprecated* is “strongly disapproved of; *in computing:* planned to be phased out, but still available for use”. If you look at the official docs for `@Deprecated`, they seem to go with the generic definition rather than the computing-specific one. OTOH, I asked a similar question (whether marking unstable features was an intended use case for `@Deprecated`) and the comments I got recommended against using it in this manner. – user149408 Jan 05 '21 at 16:36

1 Answers1

6

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);
}
Florian Genser
  • 160
  • 2
  • 7