Deprecate the StableAPI annotations, switch to JB annotations

Author: FalsePattern

README.MD

@@ -2,7 +2,6 @@ A library for 1.7.10 with lots of useful stuff, licensed under the LGPLv3 licens
 
 | Package                                                         | Contents / Purpose                                                                                                                      |
 |-----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
-| [.](src/main/java/com/falsepattern/lib)                         | StableAPI and DeprecationDetails annotations                                                                                            |
 | [asm](src/main/java/com/falsepattern/lib/asm)                   | ASM helper code                                                                                                                         |
 | [compat](src/main/java/com/falsepattern/lib/compat)             | Code backported from vanilla 1.12.2                                                                                                     |
 | [config](src/main/java/com/falsepattern/lib/config)             | 1.12.2-style annotation-based config library                                                                                            |
@@ -26,8 +25,5 @@ The contents of the [util](src/main/java/com/falsepattern/lib/util) package so f
 | [RenderUtil](src/main/java/com/falsepattern/lib/util/RenderUtil.java)        | Rendering tools. Currently, the only thing implemented is a way to grab the current partial tick time from the minecraft instance |
 | [ResourceUtil](src/main/java/com/falsepattern/lib/util/ResourceUtil.java)    | Methods for efficiently retrieving resources from SPECIFIC jar files instead of the entire classpath                              |
 
-See the [@StableAPI](src/main/java/com/falsepattern/lib/StableAPI.java) annotation's javadoc for more information about
-API stability.
-
 The update checker module and the library downloader module can be toggled with the `ENABLE_UPDATE_CHECKER` and 
 `ENABLE_LIBRARY_DOWNLOADS` booleans in the `falsepatternlib.cfg` config file respectively.

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

@@ -27,23 +27,33 @@
 import java.lang.annotation.RetentionPolicy;
 
 /**
+ * DEPRECATED: Use the jetbrains annotations/jspecify instead!
+ * <p>
  * 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.
+ * @since 0.10.0
  */
+@Deprecated(since = "1.7.0")
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
-@StableAPI(since = "0.10.0")
 public @interface DeprecationDetails {
-    @StableAPI.Expose String deprecatedSince();
+    String deprecatedSince();
 
-    @StableAPI.Expose(since = "0.11.0") String replacement() default "";
+    /**
+     * @since 0.11.0
+     */
+    String replacement() default "";
 
     /**
+     * DEPRECATED: Use the jetbrains annotations/jspecify instead!
+     * <p>
      * This marks an API for removal in a future version.
+     *
+     * @since 0.12.0
      */
+    @Deprecated(since = "1.7.0")
     @Documented
     @Retention(RetentionPolicy.RUNTIME)
-    @StableAPI(since = "0.12.0")
     @interface RemovedInVersion {
         String value();
     }

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

@@ -28,6 +28,8 @@
 import java.lang.annotation.Target;
 
 /**
+ * DEPRECATED: Use the jetbrains annotations/jspecify instead!
+ * <p>
  * Anything annotated with this annotation will be considered stable, and the class/method/field will not get breaking
  * changes without a full deprecation cycle.
  * <p>
@@ -52,18 +54,21 @@
  * is highly experimental and may be removed or change at any time, however, using it in third party projects is not an
  * error, unlike __INTERNAL__, but if any issues arise from the usage of the API or the API changing, the API developer
  * shall not be blamed for it.
+ * @since 0.6.0
  */
+@Deprecated(since = "1.7.0")
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
-@StableAPI(since = "0.6.0")
 public @interface StableAPI {
     /**
      * The version this API was introduced/stabilized in. Used for library version tracking.
      */
-    @StableAPI.Expose String since();
+    String since();
 
     /**
+     * DEPRECATED: Use the jetbrains annotations/jspecify instead!
+     * <p>
      * You may use this annotation if you want a member to have an equal effective {@link #since()} value as its owner
      * class.
      * <p>
@@ -72,24 +77,30 @@
      * <p>
      * Also note that this only works for class members (methods and fields),
      * inner classes still need to use {@link StableAPI}.
+     *
+     * @since 0.10.0
      */
+    @Deprecated(since = "1.7.0")
     @Documented
     @Retention(RetentionPolicy.RUNTIME)
     @Target({ElementType.FIELD, ElementType.METHOD, ElementType.CONSTRUCTOR})
-    @StableAPI(since = "0.10.0")
     @interface Expose {
-        @StableAPI.Expose String since() default "__PARENT__";
+        String since() default "__PARENT__";
     }
 
     /**
+     * DEPRECATED: Use the jetbrains annotations/jspecify instead!
+     * <p>
      * Use this if you want to explicitly mark specific members of a {@link StableAPI} class as internal-use only.
      * <p>
      * Library consumers should never use class members marked with this annotation, as said members can be freely
      * changed or removed in any version in the library without prior notice.
+     *
+     * @since 0.10.0
      */
+    @Deprecated(since = "1.7.0")
     @Documented
     @Retention(RetentionPolicy.RUNTIME)
     @Target({ElementType.FIELD, ElementType.METHOD, ElementType.CONSTRUCTOR})
-    @StableAPI(since = "0.10.0")
     @interface Internal {}
 }

src/main/java/com/falsepattern/lib/asm/ASMUtil.java

@@ -21,7 +21,6 @@
  */
 package com.falsepattern.lib.asm;
 
-import com.falsepattern.lib.StableAPI;
 import com.falsepattern.lib.asm.exceptions.AsmClassNotFoundException;
 import com.falsepattern.lib.asm.exceptions.AsmFieldNotFoundException;
 import com.falsepattern.lib.asm.exceptions.AsmMethodNotFoundException;
@@ -44,9 +43,7 @@
 import java.util.Arrays;
 import java.util.Objects;
 
-@StableAPI(since = "0.10.0")
 public class ASMUtil {
-    @StableAPI.Expose
     public static FieldNode findFieldStandard(ClassNode cn, String name, boolean optional) {
         for (final FieldNode ret : cn.fields) {
             if (name.equals(ret.name)) {
@@ -60,7 +57,6 @@ public static FieldNode findFieldStandard(ClassNode cn, String name, boolean opt
     }
 
     @SneakyThrows
-    @StableAPI.Expose
     public static FieldNode findFieldFromMCP(ClassNode cn, String fieldName, boolean optional) {
         val classMapping = discoverClassMappingType(cn);
         if (classMapping == null) {
@@ -76,7 +72,6 @@ public static FieldNode findFieldFromMCP(ClassNode cn, String fieldName, boolean
                                  optional);
     }
 
-    @StableAPI.Expose
     public static FieldNode findFieldFromUniversal(ClassNode cn, UniversalField field, boolean optional) {
         String[] possibilities = CoreLoadingPlugin.isObfuscated() ? new String[]{field.getName(MappingType.SRG),
                                                                                  field.getName(MappingType.Notch)}
@@ -93,7 +88,6 @@ public static FieldNode findFieldFromUniversal(ClassNode cn, UniversalField fiel
                 possibilities.length == 1 ? possibilities[0] : Arrays.toString(possibilities));
     }
 
-    @StableAPI.Expose
     public static MethodNode findMethodStandard(ClassNode cn, String name, String descriptor, boolean optional) {
         for (final MethodNode ret : cn.methods) {
             if (name.equals(ret.name) && descriptor.equals(ret.desc)) {
@@ -107,7 +101,6 @@ public static MethodNode findMethodStandard(ClassNode cn, String name, String de
     }
 
     @SneakyThrows
-    @StableAPI.Expose
     public static MethodNode findMethodFromMCP(ClassNode cn, String mcpName, String mcpDescriptor, boolean optional) {
         val classMapping = discoverClassMappingType(cn);
         if (classMapping == null) {
@@ -121,7 +114,6 @@ public static MethodNode findMethodFromMCP(ClassNode cn, String mcpName, String
         return findMethodStandard(cn, method.getName(classMapping), method.getDescriptor(classMapping), optional);
     }
 
-    @StableAPI.Expose
     public static MethodNode findMethodFromUniversal(ClassNode cn, UniversalMethod method, boolean optional) {
         String[] possibleNames = CoreLoadingPlugin.isObfuscated() ? new String[]{method.getName(MappingType.SRG),
                                                                                  method.getName(MappingType.Notch)}
@@ -142,7 +134,6 @@ public static MethodNode findMethodFromUniversal(ClassNode cn, UniversalMethod m
                 possibleDescriptors.length == 1 ? possibleDescriptors[0] : Arrays.toString(possibleDescriptors));
     }
 
-    @StableAPI.Expose
     public static MappingType discoverClassMappingType(ClassNode cn) {
         if (!CoreLoadingPlugin.isObfuscated()) {
             if (MappingManager.containsClass(NameType.Internal, MappingType.MCP, cn.name)) {
@@ -156,7 +147,6 @@ public static MappingType discoverClassMappingType(ClassNode cn) {
         return null;
     }
 
-    @StableAPI.Expose
     public static UniversalClass toUniversalClass(ClassNode cn) {
         if (!CoreLoadingPlugin.isObfuscated()) {
             try {
@@ -177,22 +167,19 @@ public static UniversalClass toUniversalClass(ClassNode cn) {
         }
     }
 
-    @StableAPI.Expose
     public static ClassNode parseClass(byte[] bytes, int readerFlags) {
         val cn = new ClassNode(Opcodes.ASM5);
         val reader = new ClassReader(bytes);
         reader.accept(cn, readerFlags);
         return cn;
     }
 
-    @StableAPI.Expose
     public static byte[] serializeClass(ClassNode cn, int writerFlags) {
         val writer = new ClassWriter(writerFlags);
         cn.accept(writer);
         return writer.toByteArray();
     }
 
-    @StableAPI.Expose
     public static boolean anyEquals(String str, String... options) {
         for (val option : options) {
             if (Objects.equals(str, option)) {

src/main/java/com/falsepattern/lib/asm/IClassNodeTransformer.java

@@ -21,29 +21,21 @@
  */
 package com.falsepattern.lib.asm;
 
-import com.falsepattern.lib.DeprecationDetails;
-import com.falsepattern.lib.StableAPI;
 import org.objectweb.asm.tree.ClassNode;
 
 /**
  * See: {@link com.falsepattern.lib.turboasm.TurboClassTransformer}.
  * This class will not be removed, for backwards compatibility reasons.
  */
-@StableAPI(since = "0.10.0")
-@Deprecated
-@DeprecationDetails(deprecatedSince = "1.2.0")
+@Deprecated(since = "1.2.0")
 public interface IClassNodeTransformer {
-    @StableAPI.Expose
     String getName();
 
-    @StableAPI.Expose
     boolean shouldTransform(ClassNode cn, String transformedName, boolean obfuscated);
 
-    @StableAPI.Expose
     default int internalSortingOrder() {
         return 0;
     }
 
-    @StableAPI.Expose
     void transform(ClassNode cn, String transformedName, boolean obfuscated);
 }

src/main/java/com/falsepattern/lib/asm/SmartTransformer.java

@@ -21,8 +21,6 @@
  */
 package com.falsepattern.lib.asm;
 
-import com.falsepattern.lib.DeprecationDetails;
-import com.falsepattern.lib.StableAPI;
 import com.falsepattern.lib.internal.asm.CoreLoadingPlugin;
 import lombok.val;
 import org.apache.logging.log4j.Logger;
@@ -39,14 +37,10 @@
  * See: {@link com.falsepattern.lib.turboasm.MergeableTurboTransformer}.
  * This class will not be removed, for backwards compatibility reasons.
  */
-@StableAPI(since = "0.10.0")
-@Deprecated
-@DeprecationDetails(deprecatedSince = "1.2.0")
+@Deprecated(since = "1.2.0")
 public interface SmartTransformer extends IClassTransformer {
-    @StableAPI.Expose
     Logger logger();
 
-    @StableAPI.Expose
     List<IClassNodeTransformer> transformers();
 
     @Override

src/main/java/com/falsepattern/lib/asm/exceptions/AsmClassNotFoundException.java

@@ -21,11 +21,10 @@
  */
 package com.falsepattern.lib.asm.exceptions;
 
-import com.falsepattern.lib.StableAPI;
+import org.jetbrains.annotations.ApiStatus;
 
-@StableAPI(since = "0.10.0")
 public class AsmClassNotFoundException extends AsmTransformException {
-    @StableAPI.Internal
+    @ApiStatus.Internal
     public AsmClassNotFoundException(final String clazz) {
         super("can't find class " + clazz);
     }

src/main/java/com/falsepattern/lib/asm/exceptions/AsmFieldNotFoundException.java

@@ -21,11 +21,10 @@
  */
 package com.falsepattern.lib.asm.exceptions;
 
-import com.falsepattern.lib.StableAPI;
+import org.jetbrains.annotations.ApiStatus;
 
-@StableAPI(since = "0.10.0")
 public class AsmFieldNotFoundException extends AsmTransformException {
-    @StableAPI.Internal
+    @ApiStatus.Internal
     public AsmFieldNotFoundException(final String field) {
         super("can't find field " + field);
     }

src/main/java/com/falsepattern/lib/asm/exceptions/AsmMethodNotFoundException.java

@@ -21,10 +21,10 @@
  */
 package com.falsepattern.lib.asm.exceptions;
 
-import com.falsepattern.lib.StableAPI;
+import org.jetbrains.annotations.ApiStatus;
 
-@StableAPI(since = "0.10.0")
 public class AsmMethodNotFoundException extends AsmTransformException {
+    @ApiStatus.Internal
     public AsmMethodNotFoundException(final String method) {
         super("can't find method " + method);
     }

src/main/java/com/falsepattern/lib/asm/exceptions/AsmTransformException.java

@@ -21,21 +21,15 @@
  */
 package com.falsepattern.lib.asm.exceptions;
 
-import com.falsepattern.lib.StableAPI;
-
-@StableAPI(since = "0.10.0")
 public class AsmTransformException extends RuntimeException {
-    @StableAPI.Expose
     public AsmTransformException(final String message) {
         super(message);
     }
 
-    @StableAPI.Expose
     public AsmTransformException(final Throwable cause) {
         super(cause);
     }
 
-    @StableAPI.Expose
     public AsmTransformException(final String message, final Throwable cause) {
         super(message, cause);
     }