Annotate all the things

Author: FalsePattern

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

@@ -12,7 +12,6 @@
 @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();
+    @StableAPI.Expose
+    String deprecatedSince();
 }

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

@@ -21,8 +21,10 @@
 package com.falsepattern.lib;
 
 import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /**
  * Anything annotated with this annotation will be considered stable, and the class/method/field will not get breaking
@@ -31,17 +33,55 @@
  * 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 you have a class implementing another class, you don't need to annotate the {@link Override}-annotated methods with
+ * StableAPI, because the StableAPI system conforms to inheritance. You should still annotate the class itself, or any extra
+ * fields or non-override methods you may have added if you want to expose those too.
+ * <p>
  * 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.
+ * <p>
+ * You may set the {@link #since()} attribute to "__INTERNAL__", this will signal that even though the specific class/member
+ * has been marked as stable, it is still for internal use only. This may be done for reference purposes in multi-developer
+ * projects, where you need to communicate intent even in internal code.
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
+@Target(value = {ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.CONSTRUCTOR})
 @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();
+
+    /**
+     * You may use this annotation if you want a member to have an equal effective {@link #since()} value as its owner
+     * class.
+     * <p>
+     * Everything else from the {@link StableAPI} class still applies, this is only here for brevity's sake.
+     * Note that if you add a new field in a version newer than the class, you must use {@link StableAPI} with the
+     * correct version!
+     * <p>
+     * Also note that this only works for class members (methods and fields),
+     * inner classes still need to use {@link StableAPI}.
+     */
+    @Documented
+    @Retention(RetentionPolicy.RUNTIME)
+    @Target(value = {ElementType.FIELD, ElementType.METHOD, ElementType.CONSTRUCTOR})
+    @StableAPI(since = "0.10.0")
+    @interface Expose {}
+
+    /**
+     * 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.
+     */
+    @Documented
+    @Retention(RetentionPolicy.RUNTIME)
+    @Target(value = {ElementType.FIELD, ElementType.METHOD, ElementType.CONSTRUCTOR})
+    @StableAPI(since = "0.10.0")
+    @interface Internal {}
 }

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

@@ -20,6 +20,7 @@
  */
 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;
@@ -42,7 +43,9 @@
 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)) {
@@ -56,6 +59,7 @@ 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) {
@@ -67,6 +71,7 @@ public static FieldNode findFieldFromMCP(ClassNode cn, String fieldName, boolean
                                                    .getName(classMapping), 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)}
@@ -83,6 +88,7 @@ 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)) {
@@ -96,6 +102,7 @@ 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) {
@@ -107,6 +114,7 @@ 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)}
@@ -127,6 +135,7 @@ 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)) {
@@ -140,6 +149,7 @@ public static MappingType discoverClassMappingType(ClassNode cn) {
         return null;
     }
 
+    @StableAPI.Expose
     public static UniversalClass toUniversalClass(ClassNode cn) {
         if (CoreLoadingPlugin.isObfuscated()) {
             try {
@@ -160,18 +170,21 @@ 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);
         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

@@ -20,16 +20,22 @@
  */
 package com.falsepattern.lib.asm;
 
+import com.falsepattern.lib.StableAPI;
 import org.objectweb.asm.tree.ClassNode;
 
+@StableAPI(since = "0.10.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

@@ -20,6 +20,7 @@
  */
 package com.falsepattern.lib.asm;
 
+import com.falsepattern.lib.StableAPI;
 import com.falsepattern.lib.internal.CoreLoadingPlugin;
 import lombok.val;
 import org.apache.logging.log4j.Logger;
@@ -35,9 +36,12 @@
 /**
  * An ASM transformation dispatcher utility, inspired by mixins.
  */
+@StableAPI(since = "0.10.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

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

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

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

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

@@ -20,6 +20,9 @@
  */
 package com.falsepattern.lib.asm.exceptions;
 
+import com.falsepattern.lib.StableAPI;
+
+@StableAPI(since = "0.10.0")
 public class AsmMethodNotFoundException extends AsmTransformException {
     public AsmMethodNotFoundException(final String method) {
         super("can't find method " + method);

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

@@ -20,15 +20,21 @@
  */
 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);
     }