From f84a7fb1681030b5cdbd5f068b5957fabe6a4579 Mon Sep 17 00:00:00 2001
From: FalsePattern <30945458+FalsePattern@users.noreply.github.com>
Date: Sat, 30 Jul 2022 20:33:02 +0200
Subject: [PATCH] API annotation updates

---
 .../falsepattern/lib/DeprecationDetails.java  | 19 +++++++++++++++++++
 .../java/com/falsepattern/lib/StableAPI.java  | 10 +++++++---
 2 files changed, 26 insertions(+), 3 deletions(-)
 create mode 100644 src/main/java/com/falsepattern/lib/DeprecationDetails.java

diff --git a/src/main/java/com/falsepattern/lib/DeprecationDetails.java b/src/main/java/com/falsepattern/lib/DeprecationDetails.java
new file mode 100644
index 0000000..2a83646
--- /dev/null
+++ b/src/main/java/com/falsepattern/lib/DeprecationDetails.java
@@ -0,0 +1,19 @@
+package com.falsepattern.lib;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * Used together with {@link Deprecated} to specify when an API was marked stable, and when it was marked for deprecation.
+ * Deprecated classes MAY be removed after a full deprecation cycle as described inside the {@link StableAPI} javadoc.
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@StableAPI(since = "0.10.0")
+public @interface DeprecationDetails {
+    @StableAPI(since = "0.10.0")
+    String stableSince() default "";
+    @StableAPI(since = "0.10.0")
+    String deprecatedSince();
+}
diff --git a/src/main/java/com/falsepattern/lib/StableAPI.java b/src/main/java/com/falsepattern/lib/StableAPI.java
index d0ba2ae..53548f3 100644
--- a/src/main/java/com/falsepattern/lib/StableAPI.java
+++ b/src/main/java/com/falsepattern/lib/StableAPI.java
@@ -31,14 +31,18 @@ import java.lang.annotation.RetentionPolicy;
  * If a class or method is NOT annotated with this annotation, it will be considered unstable, and the package/method
  * arguments/etc. can freely change between patch releases without notice.
  * <p>
- * If a class is annotated with this annotation, all currently existing public and protected members in the class will
- * be considered stable.
+ * NOTICE: You should no longer use this annotation exclusively on classes themselves, and instead, annotate every single
+ * public or protected member you want to expose as a public API!
  * <p>
  * Private members will never be considered stable, and can be removed without notice.
  */
 @Documented
-@Retention(RetentionPolicy.CLASS)
+@Retention(RetentionPolicy.RUNTIME)
 @StableAPI(since = "0.6.0")
 public @interface StableAPI {
+    /**
+     * The version this API was introduced/stabilized in. Used for library version tracking.
+     */
+    @StableAPI(since = "0.6.0")
     String since();
 }