RequiresOptIn

@Target([AnnotationTarget.ANNOTATION_CLASS]) annotation class RequiresOptIn

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

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

Предполагаемое использование маркеров включения включает, но не ограничивается следующим:

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

Заразительность

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

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

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

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

@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 тип напрямую, соответствующее предупреждение или ошибка включения будут активированы в каждом месте вызова из-за заразительности распространения. Обратите внимание, что распространение не является транзитивным, т. е. вызовы outerFun сами по себе не будут вызывать дополнительных требований к включению.

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

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

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

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

Любое использование Unstable, NestedClass, или их членов будет требовать явного включения.

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

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

См. также документацию языка Kotlin для получения дополнительной информации.