Add a VcrBeta opt-in annotation.

Author: nedtwigg

jvm/selfie-lib/src/commonMain/kotlin/com/diffplug/selfie/Selfie.kt

@@ -88,5 +88,20 @@ object Selfie {
   @JvmStatic
   fun <T> cacheSelfieBinary(roundtrip: Roundtrip<T, ByteArray>, toCache: Cacheable<T>) =
       CacheSelfieBinary<T>(deferredDiskStorage, roundtrip, toCache)
-  @JvmStatic fun vcrTestLocator(sub: String = "") = VcrSelfie.TestLocator(sub, deferredDiskStorage)
+
+  /**
+   * Whichever file calls this method is where Selfie will look for `//selfieonce` comments to
+   * control whether the VCR is writing or reading. If the caller lives in a package called
+   * `selfie.*` it will keep looking up the stack trace until a caller is not inside `selfie.*`.
+   */
+  @JvmStatic
+  @VcrBeta
+  fun vcrTestLocator(sub: String = "") = VcrSelfie.TestLocator(sub, deferredDiskStorage)
 }
+
+@RequiresOptIn(
+    level = RequiresOptIn.Level.WARNING,
+    message = "This API is in beta and may change in the future.")
+@Retention(AnnotationRetention.BINARY)
+@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY)
+annotation class VcrBeta