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 для получения дополнительной информации.