<init>

Требования к платформе и версии: JVM (1.0), JS (1.0), Native (1.0)

RequiresOptIn(
    message: String = "", 
    level: 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 для получения дополнительной информации.