From 1894f0b08401971379970f204376fc2b9561a22c Mon Sep 17 00:00:00 2001 From: Mumfrey Date: Mon, 5 Jan 2015 16:31:16 +0000 Subject: [PATCH] Overhaul javadoc on @Overwrite to clarify its purpose --- .../java/org/spongepowered/asm/mixin/Overwrite.java | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/main/java/org/spongepowered/asm/mixin/Overwrite.java b/src/main/java/org/spongepowered/asm/mixin/Overwrite.java index 4d99276a..f0b455ad 100644 --- a/src/main/java/org/spongepowered/asm/mixin/Overwrite.java +++ b/src/main/java/org/spongepowered/asm/mixin/Overwrite.java @@ -30,7 +30,17 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Used to indicate a Mixin class member which should overwrite a method in the target class + *

Annotation used to indicate a mixin class member which must overwrite an obfuscated method in the target class.

+ * + *

The default behaviour of mixin classes when merging mixin methods is to replace methods in the target class which already exist, and simply add + * any other methods to the target class body as new members. This default behaviour allows methods in the target class to be easily overwritten by + * simply creating a method in the mixin with a signature matching the member to be overwritten.

+ * + *

This is not sufficient for obfuscated methods however, since as mixins traverse the obfuscation boundary, this association with the target + * method is lost because the method name will change. The {@link Overwrite} annotation is used to indicate to the annotation processor that this + * method is intended to overwrite a member in the target class, and should therefore be added to the obfuscation table.

+ * + *

Adding this annotation to a non-obfuscated method will cause the annotation processor to raise an error at compile time.

*/ @Target({ ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME)