Аннотирование неустойчивых классов/методов для Javadoc

Question

При разработке новых классов/методов для Java-проекта вы иногда хотите, чтобы люди опробовали ваш новый код, но не хотят гарантировать, что он будет обратно совместим в будущих версиях. В этой ситуации было бы целесообразно иметь что-то вроде аннотации @Unstable, чтобы уведомить пользователей о том, что этот код не будет иметь гарантии обратной совместимости, пока он не стабилизируется (функция @Unstable отличается от функции @Deprecated тем, что она может быть изменена или удалена не считаясь изменением). Также необходимо, чтобы такие аннотации отражались в HTML-формате, создаваемом javadoc, чтобы пользователь знал о них. Будучи очень оптимистичным, было бы полезно, если бы у вас было предупреждение о компиляторе, если вы используете код, который аннотируется @Unstable.

Есть ли какой-либо стандарт для такой функции на Java? Если нет, есть ли способ настроить javadoc, чтобы разрешить такую ​​функцию?

Answer 1

Нет, в Java нет стандарта для такой функции.

Чтобы добавить эту информацию в созданный Javadoc, вы можете использовать @Documented по вашей собственной аннотации.

import java.lang.annotation.Documented; 

@Documented 
public @interface Unstable { 
} 

С этим аннотация появится в Javadoc аннотированного типа, поля, метод и т.д.

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