SubclassOptInRequired(markerClass: KClass<out Annotation>)

Annotation that marks open for subclassing classes and interfaces, and makes implementation and extension of such declarations as requiring an explicit opt-in.

When applied, any attempt to subclass the target declaration will trigger an opt-in with the corresponding level and message.

The intended uses of subclass opt-in markers include, but are not limited to the following API:

  • Stable to use, but unstable to implement due to its further evolution.
  • Stable to use, but closed for 3rd-part implementations due to internal or technical reasons.
  • Stable to use, but delicate or fragile to implement.
  • Stable to use, but with a contract that may be weakened in the future in a backwards-incompatible manner for external implementations.

Contrary to regular RequiresOptIn, there are three ways to opt-in into the subclassing requirement:

  • Annotate declaration with the marker annotation, making it propagating.
  • Annotate declaration with OptIn in order to opt in into the provided guarantees in a non-propagating manner.
  • Annotate declaration with SubclassOptInRequired with the same marker class, making it further propagating only for subclassing.

Uses of this annotation are limited to open and abstract classes, and non-fun interfaces. Any other uses allowed by CLASS annotation target yield a compilation error.