Overhaul javadoc on @Overwrite to clarify its purpose

This commit is contained in:
Mumfrey committed 2015-01-05 16:31:16 +00:00
1 parent fb64777a41
commit 1894f0b084
1 file changed
+11 -1
@@ -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
* <p>Annotation used to indicate a mixin class member which must overwrite an obfuscated method in the target class.</p>
*
* <p>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.</p>
*
* <p>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.</p>
*
* <p>Adding this annotation to a non-obfuscated method will cause the annotation processor to raise an error at compile time.</p>
*/
@Target({ ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)