API annotation updates

Author: FalsePattern

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();
+}

src/main/java/com/falsepattern/lib/StableAPI.java

@@ -31,14 +31,18 @@
  * 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();
 }