что такое аннотация @RecentlyNonNull?

Я делаю проверку кода в Android Studio, и появляется следующее предупреждение

Probable bugs
@NotNull/@Nullable problems 
Not annotated method overrides method annotated with @RecentlyNonNull

для следующих кодов

@Override
public String toString() {
    return title;
}

Я видел аннотацию @NonNull раньше, это означает, что возвращение никогда не может быть нулевым. но что такое @RecentlyNonNull? когда я использую это?

поиск в Google приводит меня к https://android.googlesource.com/platform/tools/metalava/+/fcb3d99ad3fe17a266d066b28ceb6c526f7aa415/stub-annotations/src/main/java/android/support/annotation/Recentj.Non

который не дает никаких объяснений.

Рекомендуется добавить эту аннотацию, но что она делает?

Ответ 1

TL-DR
Рассматривайте @RecentlyNonNull как ограничение @NonNull и @NonNull его в своем коде таким же образом, поскольку @RecentlyNonNull @NonNull ограничение @NonNull.

Это означает, что в данном вопросе OP должен аннотировать переопределенный метод с помощью @NonNull чтобы он соответствовал @NonNull (преобразованному во время сборки в @RecentlyNonNull), определенному в суперклассе.

Аннотация @RecentlyNonNull не является частью API javadoc SDK.
Его нет в подпакете support поскольку он не предназначен для присутствия в исходном коде. Вместо этого он вычисляется во время сборки и заменяет @NonNull если он считается "недавним" в исходных файлах заглушки.

Поскольку это внутренняя обработка, у меня нет простого и прямого ответа на ваш вопрос, но я могу дать вам несколько советов, чтобы лучше понять эту аннотацию и ее происхождение.

1) @RecentlyNonNull или @RecentlyNullable: аннотации, созданные только в исходном файле-заглушке.

В Android сгенерированные заглушки и сгенерированные заглушки документации не @RecentlyNonNull одинакового уровня информации: @RecentlyNonNull или @RecentlyNullable могут появляться в заглушках, но никогда в заглушках документации, которые придерживаются только заглушки.

Вы можете найти информацию в исходном коде класса Options:

"$ARG_DOC_STUBS ", "Generate documentation stub source files for the API. Documentation stub " +
                "files are similar to regular stub files, but there are some differences. For example, in " +
                "the stub files, we'll use special annotations like @RecentlyNonNull instead of @NonNull to " +
                "indicate that an element is recently marked as non null, whereas in the documentation stubs we'll " +
                "just list this as @NonNull...

Этот документ googlesource подтверждает, что:

Здесь есть некоторые аннотации, которых нет в библиотеке поддержки, такие как @RecentlyNullable и @RecentlyNonNull. Они используются только в заглушках, чтобы автоматически пометить код как недавно аннотированный нулем/ненулем. Нам не нужны эти аннотации в исходном коде; недавность вычисляется во время сборки и вводится в заглушки вместо обычных нулевых аннотаций.

2) Введены аннотации для кодовых линтеров и предупреждений/ошибок IDE.

Согласно этому блогу, эти аннотации берут свое начало от поддержки Kotlin и позволяют компилятору/линтеру применять уровень серьезности ненулевого нарушения в соответствии с тем, насколько недавним является ненулевое ограничение (недавний: компиляция предупреждений, а не недавний: компиляция ошибок):

Как правило, нарушения договора об обнуляемости в Kotlin приводят к ошибкам компиляции. Но чтобы гарантировать, что новые аннотированные API совместимы с вашим существующим кодом, мы используем внутренний механизм, предоставленный командой компиляторов Kotlin, чтобы пометить API как недавно аннотированные. Недавно аннотированные API приведут только к предупреждениям, а не к ошибкам от компилятора Kotlin. Вам нужно будет использовать Kotlin 1.2.60 или более позднюю версию.

Наш план состоит в том, чтобы новые добавленные аннотации обнуляемости генерировали только предупреждения и повышали уровень серьезности ошибок, начиная с Android SDK следующего года. Цель состоит в том, чтобы предоставить вам достаточно времени для обновления кода.