RequiresOptIn

Начиная с Kotlin: 1.3

@Target(allowedTargets = [AnnotationTarget.ANNOTATION_CLASS])
annotation class RequiresOptIn(val message: String = "", val level: RequiresOptIn.Level = Level.ERROR)

Сигнализирует о том, что аннотация, которой помечен класс аннотации, является маркером API, для использования которого требуется явное opt-in.

Места вызова любого объявления, помеченного таким маркером или упоминающего в своей сигнатуре другое объявление, для которого требуется opt-in, должны явно согласиться на использование API либо с помощью OptIn, либо пометив себя этим маркером, что, в свою очередь, приводит к дальнейшему распространению требования opt-in.

Маркеры opt-in могут использоваться, помимо прочего, в следующих случаях:

• Экспериментальный API для публичного предварительного просмотра, семантика которого может измениться или который может повлиять на двоичную совместимость.

• Внутренние объявления, которые не следует использовать вне библиотеки, в которой они объявлены, но которые public по техническим причинам.

• Ненадёжный или требующий осторожного обращения API, для использования которого необходимы обширные знания, поэтому требуется явное opt-in.

Распространение требования

Если объявление помечено требованием opt-in, это требование распространяется на него: для любого использования или упоминания такого объявления в других объявлениях требуется явное opt-in. Общее правило распространения таково: если помеченное объявление перестанет существовать, нарушится работа только тех мест, в которых явно указано opt-in (или выдано соответствующее предупреждение). Это правило не подразумевает транзитивность: например, при встраивании распространение opt-in не происходит, поэтому автор функции несёт ответственность за её правильную разметку inline.

Области типов

Тип требует opt-in, если он помечен маркером opt-in или если opt-in требуется для внешнего объявления (класса или интерфейса). Любое использование объявления, в сигнатуре которого упоминается такой тип, требует явного opt-in, даже если объявление не используется непосредственно в месте вызова и само по себе не требует opt-in.

Например, рассмотрим следующие объявления, помеченные непередаваемым маркером opt-in:

@UnstableApi
class Unstable

@OptIn(UnstableApi::class)
fun foo(): Unstable = Unstable()

@OptIn(UnstableApi::class)
fun bar(arg: Unstable = Unstable()) {}

@OptIn(UnstableApi::class)
fun Unstable?.baz() {}

и соответствующие им места вызова:

fun outerFun() {
    val s = foo()
    bar()
    null.baz()
}

Хотя в местах вызова тип Unstable не упоминается напрямую, в каждом из них будет выдано соответствующее предупреждение или ошибка opt-in из-за распространения требования. Обратите внимание, что распространение не является транзитивным: вызовы самого outerFun не повлекут за собой дополнительных требований opt-in.

Лексические области

Если для типа требуется opt-in, это требование распространяется на его лексическую область и все вложенные объявления. Например, для следующей области:

@UnstableApi
class Unstable {
    fun memberFun() = ...

    class NestedClass {
        fun nestedFun() = ...
    }
}

Для любого использования Unstable, NestedClass или их функций-членов требуется явное opt-in.

Переопределённые объявления

Маркеры opt-in также распространяются через наследование и реализацию интерфейсов. Если для базового объявления требуется opt-in, его переопределение требует либо явного opt-in, либо передачи требования opt-in.

Дополнительную информацию см. в документации по языку Kotlin.