diff --git a/src/main/java/org/spongepowered/asm/mixin/Implements.java b/src/main/java/org/spongepowered/asm/mixin/Implements.java index dc0612d9..df516e3c 100644 --- a/src/main/java/org/spongepowered/asm/mixin/Implements.java +++ b/src/main/java/org/spongepowered/asm/mixin/Implements.java @@ -39,6 +39,8 @@ public @interface Implements { /** * Interfaces implemented, see javadoc in {@link Interface} + * + * @return list of interfaces to implement */ public Interface[] value(); } diff --git a/src/main/java/org/spongepowered/asm/mixin/Interface.java b/src/main/java/org/spongepowered/asm/mixin/Interface.java index c3f13551..603bd2d1 100644 --- a/src/main/java/org/spongepowered/asm/mixin/Interface.java +++ b/src/main/java/org/spongepowered/asm/mixin/Interface.java @@ -40,12 +40,16 @@ public @interface Interface { * Interface that the parent {@link Implements} indicates the mixin * implements. The interface will be hot-patched onto the target class as * part of the mixin application. + * + * @return interface to implement */ public Class iface(); /** * [Required] prefix for implementing interface methods. Works similarly to * {@link Shadow} prefixes, but must end with a dollar sign ($) + * + * @return prefix to use */ public String prefix(); diff --git a/src/main/java/org/spongepowered/asm/mixin/Mixin.java b/src/main/java/org/spongepowered/asm/mixin/Mixin.java index ada11fe3..9ef2a1cd 100644 --- a/src/main/java/org/spongepowered/asm/mixin/Mixin.java +++ b/src/main/java/org/spongepowered/asm/mixin/Mixin.java @@ -38,6 +38,8 @@ public @interface Mixin { /** * Target class(es) for this mixin + * + * @return classes this mixin targets */ public Class[] value() default { }; @@ -48,12 +50,17 @@ public @interface Mixin { * an otherwise public class using this property is an error condition and * will throw an exception at runtime. It is completely fine to specify both * public and private targets for the same mixin however. + * + * @return protected or package-private classes this mixin targets */ public String[] targets() default { }; /** * Priority for the mixin, relative to other mixins targetting the same * classes + * + * @return the mixin priority (relative to other mixins targetting the same + * class) */ public int priority() default 1000; @@ -71,6 +78,9 @@ public @interface Mixin { * mixin by setting the value here to false. Doing so will cause * the annotation processor to skip all annotations in this mixin when * building the obfuscation table. + * + * @return True to instruct the annotation processor to search for + * obfuscation mappings for this annotation */ public boolean remap() default true; } diff --git a/src/main/java/org/spongepowered/asm/mixin/MixinEnvironment.java b/src/main/java/org/spongepowered/asm/mixin/MixinEnvironment.java index 88cb53cf..74dd6671 100644 --- a/src/main/java/org/spongepowered/asm/mixin/MixinEnvironment.java +++ b/src/main/java/org/spongepowered/asm/mixin/MixinEnvironment.java @@ -126,6 +126,8 @@ public class MixinEnvironment { /** * Get mixin configurations from the blackboard + * + * @return list of registered mixin configs */ public List getMixinConfigs() { @SuppressWarnings("unchecked") @@ -139,6 +141,9 @@ public class MixinEnvironment { /** * Add a mixin configuration to the blackboard + * + * @param config Name of configuration resource to add + * @return fluent interface */ public MixinEnvironment addConfiguration(String config) { List configs = this.getMixinConfigs(); diff --git a/src/main/java/org/spongepowered/asm/mixin/Shadow.java b/src/main/java/org/spongepowered/asm/mixin/Shadow.java index f2283cb2..b08369b6 100644 --- a/src/main/java/org/spongepowered/asm/mixin/Shadow.java +++ b/src/main/java/org/spongepowered/asm/mixin/Shadow.java @@ -76,6 +76,8 @@ public @interface Shadow { * prefix then no renaming will take place likey resulting in a * failure state indicated by an {@link InvalidMixinException} at run * time.

+ * + * @return the shadow prefix */ public String prefix() default "shadow$"; // CHECKSTYLE:ON @@ -91,6 +93,9 @@ public @interface Shadow { * otherwise be generated. Setting this value to false will cause * the annotation processor to skip this annotation when attempting to build * the obfuscation table for the mixin. + * + * @return True to instruct the annotation processor to search for + * obfuscation mappings for this annotation */ public boolean remap() default true; } diff --git a/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinConfigPlugin.java b/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinConfigPlugin.java index 8e31119e..93a8e23b 100644 --- a/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinConfigPlugin.java +++ b/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinConfigPlugin.java @@ -95,6 +95,8 @@ public interface IMixinConfigPlugin { * method is called to allow the plugin to add any additional mixins to * load. It should return a list of mixin class names or return null if the * plugin does not wish to append any mixins of its own. + * + * @return additional mixins to apply */ public abstract List getMixins(); diff --git a/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinInfo.java b/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinInfo.java index 71d9518d..caf8a925 100644 --- a/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinInfo.java @@ -32,42 +32,59 @@ public interface IMixinInfo { /** * Get the simple name of the mixin + * + * @return the simple name (mixin tail minus the package) */ public abstract String getName(); /** * Get the name of the mixin class + * + * @return mixin class name */ public abstract String getClassName(); /** * Get the ref (internal name) of the mixin class + * + * @return mixin class ref (internal name) */ public abstract String getClassRef(); /** * Get the class bytecode + * + * @return mixin bytecode (raw bytecode after transformers) */ public abstract byte[] getClassBytes(); /** * True if the superclass of the mixin is not the direct superclass * of one or more targets. + * + * @return true if the mixin has a detached superclass */ public abstract boolean isDetachedSuper(); /** * Get a new tree for the class bytecode + * + * @param flags Flags to pass to the ClassReader + * @return get a new ClassNode representing the mixin's bytecode */ public abstract ClassNode getClassNode(int flags); /** * Get the target classes for this mixin + * + * @return list of target classes */ public abstract List getTargetClasses(); /** * Get the mixin priority + * + * @return the priority */ public abstract int getPriority(); } diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/At.java b/src/main/java/org/spongepowered/asm/mixin/injection/At.java index d2985e15..e1d74aeb 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/At.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/At.java @@ -70,6 +70,8 @@ public @interface At { * {@link org.spongepowered.asm.mixin.injection.points.JumpInsnPoint JUMP}. * See the javadoc for each type for more details on the scheme used by each * injection point.

+ * + * @return Injection point specifier or fully-qualified class name */ public String value(); @@ -79,12 +81,16 @@ public @interface At { * after the invoation. Use {@link At.Shift#BY BY} in conjunction * with the {@link #by} parameter to shift by an arbitrary number of * opcodes. + * + * @return Type of shift to apply */ public Shift shift() default Shift.NONE; /** * If {@link #shift} is specified as {@link At.Shift#BY BY}, specifies the * number of opcodes to shift by (negative numbers are allowed). + * + * @return Amount of shift to apply for the {@link At.Shift#BY BY} shift */ public int by() default 0; @@ -92,6 +98,8 @@ public @interface At { *

The named arguments list is used to expand the scope of the * annotation beyond the fixed values below in order to accommodate the * needs of custom injection point classes. + * + * @return Named arguments for the injection point */ public String[] args() default { }; @@ -121,6 +129,8 @@ public @interface At { /** * Target opcode for FIELD and JUMP InjectionPoints. See the javadoc for the * relevant injection point for more details. + * + * @return Bytecode opcode for supported InjectionPoints */ public int opcode() default -1; @@ -135,6 +145,9 @@ public @interface At { * this value to false will cause the annotation processor to skip * this annotation when attempting to build the obfuscation table for the * mixin. + * + * @return True to instruct the annotation processor to search for + * obfuscation mappings for this annotation */ public boolean remap() default true; } diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/Inject.java b/src/main/java/org/spongepowered/asm/mixin/injection/Inject.java index e4b03a87..425683da 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/Inject.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/Inject.java @@ -42,6 +42,8 @@ public @interface Inject { * String representation of a * {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo * MemberInfo} which identifies the target method. + * + * @return target method for this injector */ public String method(); @@ -49,6 +51,8 @@ public @interface Inject { * Array of {@link At} annotations which describe the * {@link InjectionPoint}s in the target method. Allows one or more * callbacks to be injected in the target method. + * + * @return injection point specifiers for this injector */ public At[] at(); @@ -59,12 +63,18 @@ public @interface Inject { * interacting with the supplied * {@link org.spongepowered.asm.mixin.injection.callback.CallbackInfo} * object. + * + * @return true if this injector should inject appropriate RETURN opcodes + * which allow it to be cancelled */ public boolean cancellable() default false; /** * Set to true to allow local variables to be captured from the target * method as well as method parameters. + * + * @return true if the injector should capture local variables in the frame + * at the injection point */ // public boolean captureLocals() default false; @@ -80,6 +90,9 @@ public @interface Inject { * be generated. Setting this value to false will cause the * annotation processor to skip this annotation when attempting to build the * obfuscation table for the mixin. + * + * @return True to instruct the annotation processor to search for + * obfuscation mappings for this annotation */ public boolean remap() default true; } diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/InjectionPoint.java b/src/main/java/org/spongepowered/asm/mixin/injection/InjectionPoint.java index 4367b127..24f04f05 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/InjectionPoint.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/InjectionPoint.java @@ -42,7 +42,7 @@ import org.spongepowered.asm.mixin.injection.points.BeforeStringInvoke; import org.spongepowered.asm.mixin.injection.points.JumpInsnPoint; import org.spongepowered.asm.mixin.injection.points.MethodHead; import org.spongepowered.asm.mixin.injection.struct.InjectionPointData; -import org.spongepowered.asm.mixin.transformer.MixinData; +import org.spongepowered.asm.mixin.transformer.IReferenceMapperContext; import org.spongepowered.asm.util.ASMHelper; import com.google.common.base.Joiner; @@ -235,6 +235,7 @@ public abstract class InjectionPoint { * nodes from all component injection points * * @param operands injection points to perform intersection + * @return adjusted InjectionPoint */ public static InjectionPoint and(InjectionPoint... operands) { return new InjectionPoint.Intersection(operands); @@ -245,6 +246,7 @@ public abstract class InjectionPoint { * all component injection points * * @param operands injection points to perform union + * @return adjusted InjectionPoint */ public static InjectionPoint or(InjectionPoint... operands) { return new InjectionPoint.Union(operands); @@ -255,6 +257,7 @@ public abstract class InjectionPoint { * insns from the supplied injection point * * @param point injection points to perform shift + * @return adjusted InjectionPoint */ public static InjectionPoint after(InjectionPoint point) { return new InjectionPoint.Shift(point, 1); @@ -265,6 +268,7 @@ public abstract class InjectionPoint { * insns from the supplied injection point * * @param point injection points to perform shift + * @return adjusted InjectionPoint */ public static InjectionPoint before(InjectionPoint point) { return new InjectionPoint.Shift(point, -1); @@ -275,6 +279,8 @@ public abstract class InjectionPoint { * specified "count" from insns from the supplied injection point * * @param point injection points to perform shift + * @param count amount to shift by + * @return adjusted InjectionPoint */ public static InjectionPoint shift(InjectionPoint point, int count) { return new InjectionPoint.Shift(point, count); @@ -282,16 +288,28 @@ public abstract class InjectionPoint { /** * Parse an InjectionPoint from the supplied {@link At} annotation + * + * @param mixin Data for the mixin containing the annotation, used to obtain + * the refmap, amongst other things + * @param at {@link At} annotation to parse information from + * @return InjectionPoint parsed from the supplied data or null if parsing + * failed */ - public static InjectionPoint parse(MixinData mixin, At at) { + public static InjectionPoint parse(IReferenceMapperContext mixin, At at) { return InjectionPoint.parse(mixin, at.value(), at.shift(), at.by(), Arrays.asList(at.args()), at.target(), at.ordinal(), at.opcode()); } /** * Parse an InjectionPoint from the supplied {@link At} annotation supplied * as an AnnotationNode instance + * + * @param mixin Data for the mixin containing the annotation, used to obtain + * the refmap, amongst other things + * @param node {@link At} annotation to parse information from + * @return InjectionPoint parsed from the supplied data or null if parsing + * failed */ - public static InjectionPoint parse(MixinData mixin, AnnotationNode node) { + public static InjectionPoint parse(IReferenceMapperContext mixin, AnnotationNode node) { String at = ASMHelper.getAnnotationValue(node, "value"); List args = ASMHelper.>getAnnotationValue(node, "args"); String target = ASMHelper.getAnnotationValue(node, "target", ""); @@ -310,8 +328,20 @@ public abstract class InjectionPoint { /** * Parse and instantiate an InjectionPoint from the supplied information. * Returns null if an InjectionPoint could not be created. + * + * @param mixin Data for the mixin containing the annotation, used to obtain + * the refmap, amongst other things + * @param at Injection point specifier + * @param shift Shift type to apply + * @param by Amount of shift to apply for the BY shift type + * @param args Named parameters + * @param target Target for supported injection points + * @param ordinal Ordinal offset for supported injection points + * @param opcode Bytecode opcode for supported injection points + * @return InjectionPoint parsed from the supplied data or null if parsing + * failed */ - public static InjectionPoint parse(MixinData mixin, String at, At.Shift shift, int by, + public static InjectionPoint parse(IReferenceMapperContext mixin, String at, At.Shift shift, int by, List args, String target, int ordinal, int opcode) { InjectionPointData data = new InjectionPointData(mixin, args, target, ordinal, opcode); InjectionPoint point = null; diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/ModifyArg.java b/src/main/java/org/spongepowered/asm/mixin/injection/ModifyArg.java index ada9aa04..ae83b25c 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/ModifyArg.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/ModifyArg.java @@ -41,6 +41,8 @@ public @interface ModifyArg { * String representation of a * {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo * MemberInfo} which identifies the target method. + * + * @return target method */ public String method(); @@ -49,6 +51,8 @@ public @interface ModifyArg { * the target method. The specified {@link InjectionPoint} must only * return nodes of type {@link org.objectweb.asm.tree.MethodInsnNode} and an * exception will be thrown if this is not the case. + * + * @return {@link At} which identifies the target method invocation */ public At at(); @@ -60,7 +64,9 @@ public @interface ModifyArg { * returns an integer, then the integer parameter will be automatically * selected.

* - *

The index is zero-based.

+ *

The index is zero-based.

+ * + * @return argument index to modify or -1 for automatic */ public int index() default -1; @@ -75,6 +81,9 @@ public @interface ModifyArg { * be generated. Setting this value to false will cause the * annotation processor to skip this annotation when attempting to build the * obfuscation table for the mixin. + * + * @return True to instruct the annotation processor to search for + * obfuscation mappings for this annotation */ public boolean remap() default true; } diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/Redirect.java b/src/main/java/org/spongepowered/asm/mixin/injection/Redirect.java index 926e1d04..31ba0acc 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/Redirect.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/Redirect.java @@ -41,6 +41,8 @@ public @interface Redirect { * String representation of a * {@link org.spongepowered.asm.mixin.injection.struct.MemberInfo * MemberInfo} which identifies the target method. + * + * @return method to inject into */ public String method(); @@ -49,6 +51,8 @@ public @interface Redirect { * the target method. The specified {@link InjectionPoint} must only * return nodes of type {@link org.objectweb.asm.tree.MethodInsnNode} and an * exception will be thrown if this is not the case. + * + * @return {@link At} which identifies the target method invocation */ public At at(); @@ -63,6 +67,9 @@ public @interface Redirect { * be generated. Setting this value to false will cause the * annotation processor to skip this annotation when attempting to build the * obfuscation table for the mixin. + * + * @return True to instruct the annotation processor to search for + * obfuscation mappings for this annotation */ public boolean remap() default true; } diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfo.java b/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfo.java index b8121274..60cf7b33 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfo.java @@ -55,6 +55,9 @@ public class CallbackInfo implements Cancellable { /** * This ctor is always called by injected code + * + * @param name calling method name + * @param cancellable true if the callback can be cancelled */ public CallbackInfo(String name, boolean cancellable) { this.name = name; @@ -63,6 +66,8 @@ public class CallbackInfo implements Cancellable { /** * Get the method name where this callback originated + * + * @return the name of the calling method */ public String getName() { return this.name; diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfoReturnable.java b/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfoReturnable.java index aa90b111..bfec59a8 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfoReturnable.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInfoReturnable.java @@ -99,7 +99,7 @@ public class CallbackInfoReturnable extends CallbackInfo { * Sets a return value for this callback and cancels the callback (required * in order to return the new value) * - * @param returnValue + * @param returnValue value to return */ public void setReturnValue(R returnValue) throws CancellationException { super.cancel(); diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInjector.java b/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInjector.java index e7a43b7c..742b9a2a 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInjector.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/callback/CallbackInjector.java @@ -64,6 +64,12 @@ public class CallbackInjector extends Injector { /** * Make a new CallbackInjector with the supplied args + * + * @param info information about this injector + * @param cancellable True if injections performed by this injector should + * be cancellable + * @param captureLocals True to capture local variables from the frame at + * the target location */ public CallbackInjector(InjectionInfo info, boolean cancellable, boolean captureLocals) { super(info); @@ -118,7 +124,11 @@ public class CallbackInjector extends Injector { } /** - * Generate the actual bytecode + * Generate the actual bytecode for the callback + * + * @param target Target method to inject callback into + * @param node Target node within + * @param locals Inferred local types at the target location */ private void inject(Target target, final AbstractInsnNode node, final Type[] locals) { // Calculate the initial frame size based on the target method's arguments @@ -165,7 +175,7 @@ public class CallbackInjector extends Injector { insns.add(new TypeInsnNode(Opcodes.NEW, target.callbackInfoClass)); ctorMAXS++; insns.add(new InsnNode(Opcodes.DUP)); ctorMAXS++; invokeMAXS++; // CHECKSTYLE:ON - ctorMAXS += this.invokeCallbackInfoCtor(target, insns, this.cancellable, pushReturnValue, marshallVar); + ctorMAXS += this.invokeCallbackInfoCtor(target, insns, pushReturnValue, marshallVar); insns.add(new VarInsnNode(Opcodes.ASTORE, marshallVar)); // Push "this" onto the stack if the callback is not static @@ -198,12 +208,21 @@ public class CallbackInjector extends Injector { target.method.maxStack = Math.max(target.method.maxStack, Math.max(target.maxStack + ctorMAXS, target.maxStack + invokeMAXS)); } - protected int invokeCallbackInfoCtor(Target target, InsnList insns, boolean cancellable, boolean pushReturnValue, int marshallVar) { + /** + * @param target target method + * @param insns instruction list to append to + * @param pushReturnValue True to push the current value on the stack into + * the CallbackInfo ctor, used when injecting at a RETURN opcode in + * order to capture the current return value + * @param marshallVar "working" variable used to marshallt temporary values + * @return additional MAXS slots required + */ + protected int invokeCallbackInfoCtor(Target target, InsnList insns, boolean pushReturnValue, int marshallVar) { int ctorMAXS = 0; // CHECKSTYLE:OFF insns.add(new LdcInsnNode(target.method.name)); ctorMAXS++; - insns.add(new InsnNode(cancellable ? Opcodes.ICONST_1 : Opcodes.ICONST_0)); ctorMAXS++; + insns.add(new InsnNode(this.cancellable ? Opcodes.ICONST_1 : Opcodes.ICONST_0)); ctorMAXS++; // CHECKSTYLE:ON if (pushReturnValue) { @@ -221,10 +240,10 @@ public class CallbackInjector extends Injector { /** * if (e.isCancelled()) return e.getReturnValue(); * - * @param target - * @param insns - * @param node - * @param marshallVar + * @param target target method + * @param insns instruction list to append to + * @param node target node + * @param marshallVar "working" variable used to marshallt temporary values */ protected void injectCancellationCode(Target target, final InsnList insns, final AbstractInsnNode node, int marshallVar) { insns.add(new VarInsnNode(Opcodes.ALOAD, marshallVar)); @@ -243,10 +262,10 @@ public class CallbackInjector extends Injector { /** * Inject the appropriate return code for the method type * - * @param target - * @param insns - * @param node - * @param marshallVar + * @param target target method + * @param insns instruction list to append to + * @param node target node + * @param marshallVar "working" variable used to marshallt temporary values */ protected void injectReturnCode(Target target, final InsnList insns, final AbstractInsnNode node, int marshallVar) { if (target.returnType.equals(Type.VOID_TYPE)) { diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/callback/Cancellable.java b/src/main/java/org/spongepowered/asm/mixin/injection/callback/Cancellable.java index 7e07e38b..a9c39e3d 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/callback/Cancellable.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/callback/Cancellable.java @@ -29,13 +29,18 @@ package org.spongepowered.asm.mixin.injection.callback; * Interface for things which can be cancelled */ public interface Cancellable { + /** * Get whether this is actually cancellable + * + * @return whether this is actually cancellable */ public abstract boolean isCancellable(); /** * Get whether this is cancelled + * + * @return whether this is cancelled */ public abstract boolean isCancelled(); diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/code/Injector.java b/src/main/java/org/spongepowered/asm/mixin/injection/code/Injector.java index 89beb049..16a1c469 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/code/Injector.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/code/Injector.java @@ -66,6 +66,8 @@ public abstract class Injector { /** * Make a new CallbackInjector for the supplied InjectionInfo + * + * @param info Information about this injection */ public Injector(InjectionInfo info) { this(info.getClassNode(), info.getMethod()); @@ -73,6 +75,9 @@ public abstract class Injector { /** * Make a new CallbackInjector with the supplied args + * + * @param classNode Class containing callback and target methods + * @param methodNode Callback method */ private Injector(ClassNode classNode, MethodNode methodNode) { this.classNode = classNode; @@ -82,6 +87,10 @@ public abstract class Injector { /** * Inject into the specified method at the specified injection points + * + * @param target Target method to inject into + * @param injectionPoints InjectionPoint instances which will identify + * target insns in the target method */ public final void injectInto(Target target, List injectionPoints) { this.sanityCheck(target, injectionPoints); @@ -91,6 +100,15 @@ public abstract class Injector { } } + /** + * Use the supplied InjectionPoints to find target insns in the target + * method + * + * @param into Target method + * @param injectionPoints List of injection points parsed from At + * annotations on the callback method + * @return Target insn nodes in the target method + */ protected Set findTargetNodes(MethodNode into, List injectionPoints) { Set targetNodes = new HashSet(); diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/invoke/InvokeInjector.java b/src/main/java/org/spongepowered/asm/mixin/injection/invoke/InvokeInjector.java index 76865997..ae579c3d 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/invoke/InvokeInjector.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/invoke/InvokeInjector.java @@ -39,7 +39,9 @@ import org.spongepowered.asm.mixin.injection.struct.InjectionInfo; import org.spongepowered.asm.mixin.injection.struct.Target; import org.spongepowered.asm.util.ASMHelper; - +/** + * Base class for injectors which inject at method invokes + */ public abstract class InvokeInjector extends Injector { /** @@ -54,6 +56,10 @@ public abstract class InvokeInjector extends Injector { protected final String annotationType; + /** + * @param info Information about this injection + * @param annotationType Annotation type, used for error messages + */ public InvokeInjector(InjectionInfo info, String annotationType) { super(info); this.methodArgs = Type.getArgumentTypes(this.methodNode.desc); @@ -89,22 +95,25 @@ public abstract class InvokeInjector extends Injector { } /** - * Do the injection + * Perform a single injection + * + * @param target Target to inject into + * @param node Discovered instruction node */ protected abstract void inject(Target target, MethodInsnNode node); /** - * @param args - * @param insns - * @param argMap - * @param startArg - * @param endArg + * @param args handler arguments + * @param insns InsnList to inject insns into + * @param argMap Mapping of args to local variables + * @param startArg Starting arg to consume + * @param endArg Ending arg to consume */ protected void invokeHandlerWithArgs(Type[] args, InsnList insns, int[] argMap, int startArg, int endArg) { if (!this.isStatic) { insns.add(new VarInsnNode(Opcodes.ALOAD, 0)); } - this.pushArgs(insns, args, argMap, startArg, endArg); + this.pushArgs(args, insns, argMap, startArg, endArg); insns.add(new MethodInsnNode(this.isStatic ? Opcodes.INVOKESTATIC : Opcodes.INVOKESPECIAL, this.classNode.name, this.methodNode.name, this.methodNode.desc, false)); } @@ -113,6 +122,12 @@ public abstract class InvokeInjector extends Injector { * Generate an array containing local indexes for the specified args, * returns an array of identical size to the supplied array with an * allocated local index in each corresponding position + * + * @param args Argument types + * @param start starting index + * @param local starting local index + * @return array containing a corresponding local arg index for each member + * of the supplied args array */ protected int[] generateArgMap(Type[] args, int start, int local) { int[] argMap = new int[args.length]; @@ -126,6 +141,12 @@ public abstract class InvokeInjector extends Injector { /** * Store args on the stack starting at the end and working back to position * specified by start, return the generated argMap + * + * @param target target method + * @param args argument types + * @param insns instruction list to generate insns into + * @param start Starting index + * @return the generated argmap */ protected int[] storeArgs(Target target, Type[] args, InsnList insns, int start) { int[] argMap = this.generateArgMap(args, start, target.method.maxLocals); @@ -134,7 +155,13 @@ public abstract class InvokeInjector extends Injector { } /** - * Store args on the stack to their positions allocated based on argMap + * Store args on the stack to their positions allocated based on argMap + * + * @param args argument types + * @param insns instruction list to generate insns into + * @param argMap generated argmap containing local indices for all args + * @param start Starting index + * @param end Ending index */ protected void storeArgs(Type[] args, InsnList insns, int[] argMap, int start, int end) { for (int arg = end - 1; arg >= start; arg--) { @@ -143,9 +170,14 @@ public abstract class InvokeInjector extends Injector { } /** - * Load args onto the stack from their positions allocated in argMap + * Load args onto the stack from their positions allocated in argMap + * @param args argument types + * @param insns instruction list to generate insns into + * @param argMap generated argmap containing local indices for all args + * @param start Starting index + * @param end Ending index */ - protected void pushArgs(InsnList insns, Type[] args, int[] argMap, int start, int end) { + protected void pushArgs(Type[] args, InsnList insns, int[] argMap, int start, int end) { for (int arg = start; arg < end; arg++) { insns.add(new VarInsnNode(args[arg].getOpcode(Opcodes.ILOAD), argMap[arg])); } diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/invoke/ModifyArgInjector.java b/src/main/java/org/spongepowered/asm/mixin/injection/invoke/ModifyArgInjector.java index 0158b869..379d505e 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/invoke/ModifyArgInjector.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/invoke/ModifyArgInjector.java @@ -110,7 +110,7 @@ public class ModifyArgInjector extends InvokeInjector { private int injectSingleArgHandler(Target target, Type[] args, int argIndex, InsnList insns) { int[] argMap = this.storeArgs(target, args, insns, argIndex); this.invokeHandlerWithArgs(args, insns, argMap, argIndex, argIndex + 1); - this.pushArgs(insns, args, argMap, argIndex + 1, args.length); + this.pushArgs(args, insns, argMap, argIndex + 1, args.length); return target.method.maxLocals - argMap[argMap.length - 1] - 1 + args[args.length - 1].getSize(); } @@ -124,9 +124,9 @@ public class ModifyArgInjector extends InvokeInjector { } int[] argMap = this.storeArgs(target, args, insns, 0); - this.pushArgs(insns, args, argMap, 0, argIndex); + this.pushArgs(args, insns, argMap, 0, argIndex); this.invokeHandlerWithArgs(args, insns, argMap, 0, args.length); - this.pushArgs(insns, args, argMap, argIndex + 1, args.length); + this.pushArgs(args, insns, argMap, argIndex + 1, args.length); return target.method.maxLocals - argMap[argMap.length - 1] - 1 + args[args.length - 1].getSize(); } diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionInfo.java b/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionInfo.java index 87525f89..2290e7dd 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionInfo.java @@ -92,8 +92,8 @@ public abstract class InjectionInfo { /** * ctor * - * @param mixin - * @param method Method + * @param mixin Mixin data + * @param method Injector method * @param annotation Annotation to parse */ protected InjectionInfo(MixinData mixin, MethodNode method, AnnotationNode annotation) { @@ -155,11 +155,14 @@ public abstract class InjectionInfo { this.injector = this.initInjector(this.annotation); } + // stub protected abstract Injector initInjector(AnnotationNode injectAnnotation); /** * Get whether there is enough valid information in this info to actually * perform an injection. + * + * @return true if this InjectionInfo was successfully parsed */ public boolean isValid() { return this.targets.size() > 0 && this.injectionPoints.size() > 0; @@ -175,12 +178,19 @@ public abstract class InjectionInfo { } } + /** + * Get the annotation which this InjectionInfo was created from + * + * @return The annotation which this InjectionInfo was created from + */ public AnnotationNode getAnnotation() { return this.annotation; } /** * Get the class node for this injection + * + * @return the class containing the injector and the target */ public ClassNode getClassNode() { return this.classNode; @@ -188,6 +198,8 @@ public abstract class InjectionInfo { /** * Get method being called + * + * @return injector method */ public MethodNode getMethod() { return this.method; @@ -195,6 +207,8 @@ public abstract class InjectionInfo { /** * Get methods being injected into + * + * @return methods being injected into */ public Collection getTargets() { return this.targets; diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionPointData.java b/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionPointData.java index c6b28311..a620982e 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionPointData.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionPointData.java @@ -28,7 +28,7 @@ import java.util.HashMap; import java.util.List; import java.util.Map; -import org.spongepowered.asm.mixin.transformer.MixinData; +import org.spongepowered.asm.mixin.transformer.IReferenceMapperContext; /** @@ -45,7 +45,7 @@ public class InjectionPointData { /** * Mixin */ - private final MixinData mixin; + private final IReferenceMapperContext mixin; /** * Target @@ -62,7 +62,7 @@ public class InjectionPointData { */ private final int opcode; - public InjectionPointData(MixinData mixin, List args, String target, int ordinal, int opcode) { + public InjectionPointData(IReferenceMapperContext mixin, List args, String target, int ordinal, int opcode) { this.mixin = mixin; this.target = target; this.ordinal = Math.max(-1, ordinal); diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/struct/MemberInfo.java b/src/main/java/org/spongepowered/asm/mixin/injection/struct/MemberInfo.java index e6b4193d..5fd05bdb 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/struct/MemberInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/struct/MemberInfo.java @@ -29,7 +29,7 @@ import net.minecraftforge.srg2source.rangeapplier.MethodData; import org.objectweb.asm.tree.AbstractInsnNode; import org.objectweb.asm.tree.FieldInsnNode; import org.objectweb.asm.tree.MethodInsnNode; -import org.spongepowered.asm.mixin.transformer.MixinData; +import org.spongepowered.asm.mixin.transformer.IReferenceMapperContext; /** @@ -95,22 +95,32 @@ public class MemberInfo { public final boolean matchAll; /** + * ctor + * * @param name Member name, must not be null + * @param matchAll true if this info should match all matching references, + * or only the first */ public MemberInfo(String name, boolean matchAll) { this(name, null, null, matchAll); } /** + * ctor + * * @param name Member name, must not be null * @param owner Member owner, can be null otherwise must be in internal form * without L; + * @param matchAll true if this info should match all matching references, + * or only the first */ public MemberInfo(String name, String owner, boolean matchAll) { this(name, owner, null, matchAll); } /** + * ctor + * * @param name Member name, must not be null * @param owner Member owner, can be null otherwise must be in internal form * without L; @@ -131,6 +141,8 @@ public class MemberInfo { /** * Initialise a MemberInfo using the supplied insn which must be an instance * of MethodInsnNode or FieldInsnNode. + * + * @param insn instruction node to copy values from */ public MemberInfo(AbstractInsnNode insn) { this.matchAll = false; @@ -152,6 +164,8 @@ public class MemberInfo { /** * Initialise a MemberInfo using the supplied MethodData object + * + * @param methodData MethodData object to copy values from */ public MemberInfo(MethodData methodData) { int slashPos = methodData.name.lastIndexOf('/'); @@ -176,6 +190,8 @@ public class MemberInfo { /** * Return this MemberInfo as an SRG mapping + * + * @return SRG representation of this MemberInfo */ public String toSrg() { if (!this.isFullyQualified()) { @@ -203,6 +219,8 @@ public class MemberInfo { /** * Get whether this reference is fully qualified + * + * @return true if all components of this reference are non-null */ public boolean isFullyQualified() { return this.owner != null && this.name != null && this.desc != null; @@ -211,6 +229,8 @@ public class MemberInfo { /** * Get whether this MemberInfo is definitely a field, the output of this * method is undefined if {@link #isFullyQualified} returns false. + * + * @return true if this is definitely a field */ public boolean isField() { return this.desc != null && !this.desc.startsWith("("); @@ -219,6 +239,12 @@ public class MemberInfo { /** * Test whether this MemberInfo matches the supplied values. Null values are * ignored. + + * @param owner Owner to compare with, null to skip + * @param name Name to compare with, null to skip + * @param desc Signature to compare with, null to skip + * @return true if all non-null values in this reference match non-null + * arguments supplied to this method */ public boolean matches(String owner, String name, String desc) { return this.matches(owner, name, desc, 0); @@ -227,6 +253,14 @@ public class MemberInfo { /** * Test whether this MemberInfo matches the supplied values at the specified * ordinal. Null values are ignored. + * + * @param owner Owner to compare with, null to skip + * @param name Name to compare with, null to skip + * @param desc Signature to compare with, null to skip + * @param ordinal ordinal position within the class, used to honour the + * matchAll semantics + * @return true if all non-null values in this reference match non-null + * arguments supplied to this method */ public boolean matches(String owner, String name, String desc, int ordinal) { if (this.desc != null && desc != null && !this.desc.equals(desc)) { @@ -244,6 +278,11 @@ public class MemberInfo { /** * Test whether this MemberInfo matches the supplied values. Null values are * ignored. + + * @param name Name to compare with, null to skip + * @param desc Signature to compare with, null to skip + * @return true if all non-null values in this reference match non-null + * arguments supplied to this method */ public boolean matches(String name, String desc) { return this.matches(name, desc, 0); @@ -252,6 +291,13 @@ public class MemberInfo { /** * Test whether this MemberInfo matches the supplied values at the specified * ordinal. Null values are ignored. + * + * @param name Name to compare with, null to skip + * @param desc Signature to compare with, null to skip + * @param ordinal ordinal position within the class, used to honour the + * matchAll semantics + * @return true if all non-null values in this reference match non-null + * arguments supplied to this method */ public boolean matches(String name, String desc, int ordinal) { return (this.name == null || this.name.equals(name)) @@ -261,20 +307,32 @@ public class MemberInfo { /** * Parse a MemberInfo from a string + * + * @param string String to parse MemberInfo from + * @return parsed MemberInfo */ - public static MemberInfo parse(String name) { - return MemberInfo.parse(name, null, null); + public static MemberInfo parse(String string) { + return MemberInfo.parse(string, null, null); } /** * Parse a MemberInfo from a string + * + * @param string String to parse MemberInfo from + * @param context Context to use for reference mapping + * @return parsed MemberInfo */ - public static MemberInfo parse(String name, MixinData mixin) { - return MemberInfo.parse(name, mixin.getReferenceMapper(), mixin.getClassRef()); + public static MemberInfo parse(String string, IReferenceMapperContext context) { + return MemberInfo.parse(string, context.getReferenceMapper(), context.getClassRef()); } /** * Parse a MemberInfo from a string + * + * @param name String to parse MemberInfo from + * @param refMapper Reference mapper to use + * @param mixinClass Mixin class to use for remapping + * @return parsed MemberInfo */ public static MemberInfo parse(String name, ReferenceMapper refMapper, String mixinClass) { String desc = null; diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/struct/Target.java b/src/main/java/org/spongepowered/asm/mixin/injection/struct/Target.java index 84f259f3..abd7a56a 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/struct/Target.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/struct/Target.java @@ -72,6 +72,8 @@ public class Target { /** * Make a new Target for the supplied method + * + * @param method target method */ public Target(MethodNode method) { this.method = method; @@ -86,6 +88,12 @@ public class Target { /** * Get the callback descriptor + * + * @param captureLocals True if the callback is capturing locals + * @param locals Local variable types + * @param argumentTypes Argument types + * @param startIndex local index to start at + * @return generated descriptor */ public String getCallbackDescriptor(final boolean captureLocals, final Type[] locals, Type[] argumentTypes, int startIndex) { if (!captureLocals) { diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/IReferenceMapperContext.java b/src/main/java/org/spongepowered/asm/mixin/transformer/IReferenceMapperContext.java new file mode 100644 index 00000000..5fd80fbd --- /dev/null +++ b/src/main/java/org/spongepowered/asm/mixin/transformer/IReferenceMapperContext.java @@ -0,0 +1,48 @@ +/* + * This file is part of Sponge, licensed under the MIT License (MIT). + * + * Copyright (c) SpongePowered.org + * Copyright (c) contributors + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package org.spongepowered.asm.mixin.transformer; + +import org.spongepowered.asm.mixin.injection.struct.ReferenceMapper; + +/** + * Context for performing reference mapping + */ +public interface IReferenceMapperContext { + + /** + * Get the internal mixin class name + * + * @return internal class name + */ + public abstract String getClassRef(); + + /** + * Get the reference mapper for this mixin + * + * @return ReferenceMapper instance (can be null) + */ + public abstract ReferenceMapper getReferenceMapper(); + +} diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/InterfaceInfo.java b/src/main/java/org/spongepowered/asm/mixin/transformer/InterfaceInfo.java index 53b7c246..340c2880 100644 --- a/src/main/java/org/spongepowered/asm/mixin/transformer/InterfaceInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/transformer/InterfaceInfo.java @@ -61,6 +61,9 @@ public class InterfaceInfo extends TreeInfo { /** * Make with the new thing already + * + * @param prefix Method prefix + * @param iface Interface to load */ private InterfaceInfo(String prefix, Type iface) { if (prefix == null || prefix.length() < 2 || !prefix.endsWith("$")) { @@ -82,6 +85,8 @@ public class InterfaceInfo extends TreeInfo { /** * Reads an interface and its super-interfaces and gathers method names in * to the local "methods" collection + * + * @param ifaceName Name of the interface to read */ private void readInterface(String ifaceName) { ClassNode ifaceNode = new ClassNode(); @@ -105,6 +110,8 @@ public class InterfaceInfo extends TreeInfo { /** * Get the prefix string (non null) + * + * @return the prefix */ public String getPrefix() { return this.prefix; @@ -112,6 +119,8 @@ public class InterfaceInfo extends TreeInfo { /** * Get the interface type + * + * @return interface type */ public Type getIface() { return this.iface; @@ -119,6 +128,8 @@ public class InterfaceInfo extends TreeInfo { /** * Get the internal name of the interface + * + * @return the internal name for the interface */ public String getInternalName() { return this.iface.getInternalName(); @@ -128,7 +139,10 @@ public class InterfaceInfo extends TreeInfo { * Processes a method node in the mixin and renames it if necessary. If the * prefix is found then we verify that the method exists in the target * interface and throw our teddies out of the pram if that's not the case - * (replacement behaviour for {@link Override} essentially. + * (replacement behaviour for {@link Override} essentially. + * + * @param method Method to rename + * @return true if the method was remapped */ public boolean renameMethod(MethodNode method) { if (this.methods == null) { @@ -152,6 +166,9 @@ public class InterfaceInfo extends TreeInfo { /** * Convert an {@link Interface} annotation node into an * {@link InterfaceInfo} + * + * @param node Annotation node to process + * @return parsed InterfaceInfo object */ static InterfaceInfo fromAnnotation(AnnotationNode node) { String prefix = ASMHelper.getAnnotationValue(node, "prefix"); diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinData.java b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinData.java index d67ba665..bc464663 100644 --- a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinData.java +++ b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinData.java @@ -39,7 +39,6 @@ import org.objectweb.asm.tree.ClassNode; import org.objectweb.asm.tree.MethodInsnNode; import org.objectweb.asm.tree.MethodNode; import org.spongepowered.asm.mixin.Implements; -import org.spongepowered.asm.mixin.InvalidMixinException; import org.spongepowered.asm.mixin.Shadow; import org.spongepowered.asm.mixin.injection.struct.ReferenceMapper; import org.spongepowered.asm.mixin.injection.struct.Target; @@ -51,7 +50,7 @@ import org.spongepowered.asm.util.ASMHelper; * any pre-transformations required by the mixin class itself such as method * renaming and any other pre-processing of the mixin bytecode. */ -public class MixinData { +public class MixinData implements IReferenceMapperContext { /** * Mixin info @@ -92,7 +91,8 @@ public class MixinData { /** * ctor * - * @param info + * @param info Mixin information + * @param target target class */ MixinData(MixinInfo info, ClassNode target) { this.info = info; @@ -111,6 +111,8 @@ public class MixinData { /** * Get the mixin tree + * + * @return mixin tree */ public ClassNode getClassNode() { return this.classNode; @@ -118,38 +120,46 @@ public class MixinData { /** * Get the mixin class name + * + * @return the mixin class name */ public String getClassName() { return this.info.getClassName(); } - /** - * Get the internal mixin class name + /* (non-Javadoc) + * @see org.spongepowered.asm.mixin.transformer.IReferenceMapperContext + * #getClassRef() */ + @Override public String getClassRef() { return this.info.getClassRef(); } /** * Get the target class reference + * + * @return the reference of the target class (only valid on single-target + * mixins) */ public String getTargetClassRef() { - List targetClasses = this.info.getTargetClasses(); - if (targetClasses.size() != 1) { - throw new InvalidMixinException("Multiple targets found for " + this.getClassName() + " but exactly one is required"); - } - return targetClasses.get(0); + return this.targetClass.name; } /** * Get the target class + * + * @return the target class */ public ClassNode getTargetClass() { return this.targetClass; } /** - * Get a method from the target class + * Get a target method handle from the target class + * + * @param method method to get a target handle for + * @return new or existing target handle for the supplied method */ public Target getTargetMethod(MethodNode method) { if (!this.targetClass.methods.contains(method)) { @@ -167,6 +177,8 @@ public class MixinData { /** * Get the mixin priority + * + * @return the priority (only meaningful in relation to other mixins) */ public int getPriority() { return this.info.getPriority(); @@ -174,6 +186,8 @@ public class MixinData { /** * Get all interfaces for this mixin + * + * @return mixin interfaces */ public Set getInterfaces() { return this.interfaces; @@ -182,14 +196,18 @@ public class MixinData { /** * Get whether to propogate the source file attribute from a mixin onto the * target class + * + * @return true if the sourcefile property should be set on the target class */ public boolean shouldSetSourceFile() { return this.info.getParent().shouldSetSourceFile(); } - /** - * Get the reference mapper for this mixin + /* (non-Javadoc) + * @see org.spongepowered.asm.mixin.transformer.IReferenceMapperContext + * #getReferenceMapper() */ + @Override public ReferenceMapper getReferenceMapper() { return this.info.getParent().getReferenceMapper(); } @@ -292,6 +310,9 @@ public class MixinData { /** * Called immediately before the mixin is applied to targetClass + * + * @param transformedName Target class's transformed name + * @param targetClass Target class */ public void preApply(String transformedName, ClassNode targetClass) { this.info.preApply(transformedName, targetClass); @@ -299,6 +320,9 @@ public class MixinData { /** * Called immediately after the mixin is applied to targetClass + * + * @param transformedName Target class's transformed name + * @param targetClass Target class */ public void postApply(String transformedName, ClassNode targetClass) { this.info.postApply(transformedName, targetClass); diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinMerged.java b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinMerged.java index 740601a6..1029bcd7 100644 --- a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinMerged.java +++ b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinMerged.java @@ -39,8 +39,11 @@ import java.lang.annotation.Target; @Target({ ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) public @interface MixinMerged { + /** * Mixin which merged this method + * + * @return mixin name */ public String mixin(); @@ -48,6 +51,8 @@ public @interface MixinMerged { * Prioriy of the mixin which merged this method, used to allow mixins with * higher priority to overwrite methods already overwritten by those with a * lower priority. + * + * @return mixin priority */ public int priority(); } diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinTransformer.java b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinTransformer.java index 2e32be0d..2df97fe4 100644 --- a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinTransformer.java +++ b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinTransformer.java @@ -333,9 +333,9 @@ public class MixinTransformer extends TreeTransformer { } /** - * @param transformedName - * @param targetClass - * @param mixins + * @param transformedName Target class transformed name + * @param targetClass Target class + * @param mixins Mixin which were just applied */ protected void postTransform(String transformedName, ClassNode targetClass, SortedSet mixins) { // Stub for subclasses @@ -344,9 +344,9 @@ public class MixinTransformer extends TreeTransformer { /** * Apply the mixin described by mixin to the supplied classNode * - * @param transformedName - * @param targetClass - * @param mixin + * @param transformedName Target class transformed name + * @param targetClass Target class + * @param mixin Mixin to apply */ protected void applyMixin(String transformedName, ClassNode targetClass, MixinData mixin) { try { @@ -505,7 +505,7 @@ public class MixinTransformer extends TreeTransformer { * @param method * @param insn */ - private void updateStaticBindings(MixinData mixin, ClassNode target, MethodNode method, MethodInsnNode insn) { + private void updateStaticBindings(IReferenceMapperContext mixin, ClassNode target, MethodNode method, MethodInsnNode insn) { if (INIT.equals(method.name) || insn.owner.equals(target.name) || target.name.startsWith("<")) { return; } diff --git a/src/main/java/org/spongepowered/asm/transformers/TreeTransformer.java b/src/main/java/org/spongepowered/asm/transformers/TreeTransformer.java index c3fcad83..5362ba04 100644 --- a/src/main/java/org/spongepowered/asm/transformers/TreeTransformer.java +++ b/src/main/java/org/spongepowered/asm/transformers/TreeTransformer.java @@ -40,7 +40,7 @@ public abstract class TreeTransformer implements IClassTransformer { private ClassNode classNode; /** - * @param basicClass + * @param basicClass Original bytecode * @return tree */ protected final ClassNode readClass(byte[] basicClass) { @@ -48,7 +48,9 @@ public abstract class TreeTransformer implements IClassTransformer { } /** - * @param basicClass + * @param basicClass Original bytecode + * @param cacheReader True to cache the classReader instance for use when + * writing the generated ClassNode later * @return tree */ protected final ClassNode readClass(byte[] basicClass, boolean cacheReader) { @@ -63,7 +65,8 @@ public abstract class TreeTransformer implements IClassTransformer { } /** - * @param classNode + * @param classNode ClassNode to write out + * @return generated bytecode */ protected final byte[] writeClass(ClassNode classNode) { // Use optimised writer for speed diff --git a/src/main/java/org/spongepowered/asm/util/ASMHelper.java b/src/main/java/org/spongepowered/asm/util/ASMHelper.java index a9c7b7e1..4beec5d1 100644 --- a/src/main/java/org/spongepowered/asm/util/ASMHelper.java +++ b/src/main/java/org/spongepowered/asm/util/ASMHelper.java @@ -114,6 +114,7 @@ public class ASMHelper { * @param name Name of method to generate * @param forwardname Name of method to call * @param rettype Return type of method + * @param argtype Argument type */ public static void generateStaticForwardingMethod(ClassNode clazz, String name, String forwardname, Type rettype, Type argtype) { MethodNode method = new MethodNode(Opcodes.ASM5, @@ -133,6 +134,7 @@ public class ASMHelper { * @param name Name of method to generate * @param forwardname Name of method to call * @param rettype Return type of method + * @param fowardtype Forward type */ public static void generateForwardingToStaticMethod(ClassNode clazz, String name, String forwardname, Type rettype, Type fowardtype) { MethodNode method = new MethodNode(Opcodes.ASM5, Opcodes.ACC_PUBLIC | Opcodes.ACC_SYNTHETIC, name, @@ -151,6 +153,7 @@ public class ASMHelper { * @param name Name of method to generate * @param forwardname Name of method to call * @param rettype Return type of method + * @param fowardtype Forward type * @param thistype Type to treat 'this' as for overload searching purposes */ public static void generateForwardingToStaticMethod(ClassNode clazz, String name, String forwardname, Type rettype, Type fowardtype, @@ -278,6 +281,7 @@ public class ASMHelper { * Integer constant). * * @param c the integer to push onto the stack + * @return insn node to insert */ public static AbstractInsnNode pushIntConstant(int c) { if (c == -1) { @@ -299,6 +303,7 @@ public class ASMHelper { * @param clazz the class to scan * @param name the method name * @param desc the method descriptor + * @return discovered method node or null */ public static MethodNode findMethod(ClassNode clazz, String name, String desc) { Iterator i = clazz.methods.iterator(); @@ -567,6 +572,7 @@ public class ASMHelper { /** * Duck type the "value" entry (if any) of the specified annotation node * + * @param duck type * @param annotation Annotation node to query * @return duck-typed annotation value, null if missing, or inevitable * {@link ClassCastException} if your duck is actually a rooster @@ -579,6 +585,7 @@ public class ASMHelper { * Get the value of an annotation node and do pseudo-duck-typing via Java's * crappy generics * + * @param duck type * @param annotation Annotation node to query * @param key Key to search for * @param defaultValue Value to return if the specified key is not found or @@ -595,6 +602,7 @@ public class ASMHelper { * Get the value of an annotation node and do pseudo-duck-typing via Java's * crappy generics * + * @param duck type * @param annotation Annotation node to query * @param key Key to search for * @return duck-typed annotation value, null if missing, or inevitable @@ -625,6 +633,7 @@ public class ASMHelper { * Get the value of an annotation node as the specified enum, returns * defaultValue if the annotation value is not set * + * @param duck type * @param annotationNode Annotation node to query * @param key Key to search for * @param enumClass Class of enum containing the enum constant to search for diff --git a/src/main/java/org/spongepowered/asm/util/Locals.java b/src/main/java/org/spongepowered/asm/util/Locals.java index 225bf33f..0e8d7874 100644 --- a/src/main/java/org/spongepowered/asm/util/Locals.java +++ b/src/main/java/org/spongepowered/asm/util/Locals.java @@ -213,6 +213,7 @@ public class Locals { * * @param classNode Containing class * @param method Method + * @return generated local variable table */ public static List getLocalVariableTable(ClassNode classNode, MethodNode method) { if (method.localVariables.isEmpty()) { @@ -237,6 +238,7 @@ public class Locals { * * @param classNode Containing class * @param method Method + * @return generated local variable table */ public static List generateLocalVariableTable(ClassNode classNode, MethodNode method) { List interfaces = null;