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 1bd38b74..e7afecaf 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/ModifyArg.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/ModifyArg.java @@ -36,7 +36,37 @@ import org.spongepowered.asm.util.ConstraintParser.Constraint; /** * Specifies that this mixin method should inject an argument modifier to itself - * in the target method(s) identified by {@link #method}. + * in the target method(s) identified by {@link #method}. This type of injection + * provides a lightweight mechanism for changing a single argument of a target + * method invocation. To affect multiple arguments at once, use {@link + * ModifyArgs} instead. + * + *

Consider the following method call:

+ * + *
// x, y and z are of type float
+ *someObject.setLocation(x, y, z, true);
+ * + *

Let us assume that we wish to modify the y value in the method + * call. We know that the arguments are floats and that the y + * value is the second (index = 1) float argument. Thus our + * injector requires the following signature: + * + *

@ModifyArg(method = "...", at = ..., index = 1)
+ *private float adjustYCoord(float y) {
+ *    return y + 64.0F;
+ *}
+ * + *

The callback consumes the original value of y and returns the + * adjusted value.

+ * + *

@ModifyArg can also consume all of the target method's + * arguments if required, to provide additional context for the callback. In + * this case the arguments of the callback should match the target method:

+ * + *
@ModifyArg(method = "...", at = ..., index = 1)
+ *private float adjustYCoord(float x, float y, float z, boolean interpolate) {
+ *    return (x == 0 && y == 0) ? 0 : y;
+ *}
*/ @Target({ ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME)