From 9cd453cd634aa5cd840d32ad206283dded53acd9 Mon Sep 17 00:00:00 2001 From: Mumfrey Date: Fri, 5 Feb 2016 13:06:00 +0000 Subject: [PATCH] Add all missing class javadoc --- checkstyle.xml | 3 + .../AnnotatedMixinElementHandler.java | 4 + .../AnnotatedMixinInjectorHandler.java | 3 + .../AnnotatedMixinOverwriteHandler.java | 3 + .../AnnotatedMixinShadowHandler.java | 3 + .../tools/obfuscation/AnnotatedMixins.java | 4 + .../tools/obfuscation/MixinProcessor.java | 3 + .../tools/obfuscation/ObfuscationData.java | 17 +++ .../tools/obfuscation/ObfuscationManager.java | 3 + .../tools/obfuscation/ObfuscationType.java | 29 ++++ .../tools/obfuscation/SupportedOptions.java | 4 + .../TargetObfuscationEnvironment.java | 10 ++ .../interfaces/IMixinValidator.java | 3 + .../tools/obfuscation/struct/Message.java | 4 + .../asm/bridge/RemapperAdapter.java | 3 + .../asm/bridge/RemapperAdapterFML.java | 3 + .../asm/launch/MixinInitialisationError.java | 3 + .../asm/mixin/MixinEnvironment.java | 7 +- .../asm/mixin/MixinException.java | 3 + .../asm/mixin/RemapperChain.java | 4 + .../asm/mixin/extensibility/IMixinInfo.java | 3 + .../asm/mixin/injection/InjectionNodes.java | 129 +++++++++++++++++- .../asm/mixin/injection/InjectionPoint.java | 5 +- .../InjectionValidationException.java | 3 + .../injection/InvalidInjectionException.java | 4 + .../callback/CancellationException.java | 4 + ...InvalidImplicitDiscriminatorException.java | 4 + .../struct/CallbackInjectionInfo.java | 4 + .../InvalidMemberDescriptorException.java | 3 + .../struct/ModifyArgInjectionInfo.java | 4 + .../struct/ModifyVariableInjectionInfo.java | 4 + .../struct/RedirectInjectionInfo.java | 3 + .../injection/struct/ReferenceMapper.java | 102 +++++++++++++- .../asm/mixin/transformer/ClassInfo.java | 3 + .../transformer/InvalidMixinException.java | 3 + .../MixinTransformerModuleCheckClass.java | 3 + .../asm/obfuscation/SrgField.java | 3 + .../asm/obfuscation/SrgMethod.java | 3 + .../org/spongepowered/asm/util/ASMHelper.java | 3 + .../asm/util/LVTGeneratorException.java | 4 + .../asm/util/ObfuscationUtil.java | 6 + .../spongepowered/asm/util/PrettyPrinter.java | 8 ++ 42 files changed, 413 insertions(+), 11 deletions(-) diff --git a/checkstyle.xml b/checkstyle.xml index 3e06aaf5..538b210c 100644 --- a/checkstyle.xml +++ b/checkstyle.xml @@ -92,6 +92,9 @@ + + + diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinElementHandler.java b/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinElementHandler.java index 5a784d57..bacec1f3 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinElementHandler.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinElementHandler.java @@ -44,6 +44,10 @@ import org.spongepowered.tools.MirrorUtils; import org.spongepowered.tools.obfuscation.interfaces.IMixinAnnotationProcessor; import org.spongepowered.tools.obfuscation.interfaces.IObfuscationManager; +/** + * Base class for module for {@link AnnotatedMixin} which handle different + * aspects of mixin target classes + */ abstract class AnnotatedMixinElementHandler { /** diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinInjectorHandler.java b/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinInjectorHandler.java index 96fa77c6..075c34e0 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinInjectorHandler.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinInjectorHandler.java @@ -42,6 +42,9 @@ import org.spongepowered.tools.MirrorUtils; import org.spongepowered.tools.obfuscation.interfaces.IMixinAnnotationProcessor; import org.spongepowered.tools.obfuscation.struct.Message; +/** + * A module for {@link AnnotatedMixin} whic handles injectors + */ class AnnotatedMixinInjectorHandler extends AnnotatedMixinElementHandler { AnnotatedMixinInjectorHandler(IMixinAnnotationProcessor ap, AnnotatedMixin mixin) { diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinOverwriteHandler.java b/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinOverwriteHandler.java index 6165d6b2..1c3ebf5e 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinOverwriteHandler.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinOverwriteHandler.java @@ -34,6 +34,9 @@ import org.spongepowered.asm.obfuscation.SrgMethod; import org.spongepowered.tools.MirrorUtils; import org.spongepowered.tools.obfuscation.interfaces.IMixinAnnotationProcessor; +/** + * A module for {@link AnnotatedMixin} which handles method overwrites + */ class AnnotatedMixinOverwriteHandler extends AnnotatedMixinElementHandler { AnnotatedMixinOverwriteHandler(IMixinAnnotationProcessor ap, AnnotatedMixin mixin) { diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinShadowHandler.java b/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinShadowHandler.java index 561181d9..e470d299 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinShadowHandler.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixinShadowHandler.java @@ -33,6 +33,9 @@ import org.spongepowered.asm.obfuscation.SrgMethod; import org.spongepowered.tools.MirrorUtils; import org.spongepowered.tools.obfuscation.interfaces.IMixinAnnotationProcessor; +/** + * A module for {@link AnnotatedMixin} which handles shadowed fields and methods + */ class AnnotatedMixinShadowHandler extends AnnotatedMixinElementHandler { AnnotatedMixinShadowHandler(IMixinAnnotationProcessor ap, AnnotatedMixin mixin) { diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixins.java b/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixins.java index 657dca67..443b20e9 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixins.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/AnnotatedMixins.java @@ -75,6 +75,10 @@ class AnnotatedMixins implements IMixinAnnotationProcessor, ITokenProvider, ITyp private static final String MAPID_SYSTEM_PROPERTY = "mixin.target.mapid"; + /** + * Detected compiler argument, specifies the behaviour of some operations + * for compatibility purposes. + */ static enum CompilerEnvironment { /** * Default environment diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/MixinProcessor.java b/src/ap/java/org/spongepowered/tools/obfuscation/MixinProcessor.java index 6c585c48..028eec49 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/MixinProcessor.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/MixinProcessor.java @@ -37,6 +37,9 @@ import javax.tools.Diagnostic.Kind; import org.spongepowered.asm.mixin.Mixin; +/** + * Base class for mixin annotation processor modules + */ public abstract class MixinProcessor extends AbstractProcessor { /** diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/ObfuscationData.java b/src/ap/java/org/spongepowered/tools/obfuscation/ObfuscationData.java index 9f062fe2..31f4891e 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/ObfuscationData.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/ObfuscationData.java @@ -28,6 +28,23 @@ import java.util.HashMap; import java.util.Iterator; import java.util.Map; +import org.spongepowered.asm.obfuscation.SrgMethod; + +/** + * Return value struct for various obfuscation queries performed by the mixin + * annotation processor. + * + *

When obfuscation queries are performed by the AP, the returned data are + * encapsulated in an ObfuscationData object which contains a mapping + * of the different obfuscation types to the respective remapped value of the + * original entry for that environment.

+ * + *

The returned data are iterable over the keys, consumers should call + * {@link #get} to retrieve the remapped entries for each key.

+ * + * @param Contained type of the data, usually {@link String} for field + * and type obfuscations, and {@link SrgMethod} for methods. + */ public class ObfuscationData implements Iterable { private final Map data = new HashMap(); diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/ObfuscationManager.java b/src/ap/java/org/spongepowered/tools/obfuscation/ObfuscationManager.java index 49289b58..94fcb917 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/ObfuscationManager.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/ObfuscationManager.java @@ -43,6 +43,9 @@ import org.spongepowered.asm.util.Constants; import org.spongepowered.tools.obfuscation.interfaces.IMixinAnnotationProcessor; import org.spongepowered.tools.obfuscation.interfaces.IObfuscationManager; +/** + * Obfuscation Manager for mixin Annotation Processor + */ public class ObfuscationManager implements IObfuscationManager { /** diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/ObfuscationType.java b/src/ap/java/org/spongepowered/tools/obfuscation/ObfuscationType.java index 17528c5e..679a122b 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/ObfuscationType.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/ObfuscationType.java @@ -31,14 +31,43 @@ import org.spongepowered.tools.obfuscation.interfaces.IOptionProvider; import com.google.common.collect.ImmutableList; import com.google.common.collect.ImmutableList.Builder; +/** + * Obfuscation types supported by the annotation processor + */ enum ObfuscationType { + /** + * "SEARGE" mappings, these are unique mappings used by MCP and derived + * projects + */ SRG("searge", SupportedOptions.REOBF_SRG_FILE, SupportedOptions.REOBF_EXTRA_SRG_FILES, SupportedOptions.OUT_SRG_SRG_FILE), + + /** + * "NOTCH" mappings, internal to minecraft only + */ NOTCH("notch", SupportedOptions.REOBF_NOTCH_FILE, SupportedOptions.REOBF_EXTRA_NOTCH_FILES, SupportedOptions.OUT_NOTCH_SRG_FILE); + /** + * Refmap key for this mapping type + */ private final String key; + + /** + * The name of the Annotation Processor argument which contains the file + * name to read the SRGs for this obfuscation type from + */ private final String srgFileArgName; + + /** + * The name of the Annotation Processor argument which contains the file + * name to read the extra SRGs for this obfuscation type from + */ private final String extraSrgFilesArgName; + + /** + * The name of the Annotation Processor argument which contains the file + * name to write generated SRG mappings to + */ private final String outSrgFileArgName; private ObfuscationType(String displayName, String srgFileArgName, String extraSrgFilesArgName, String outSrgFileArgName) { diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/SupportedOptions.java b/src/ap/java/org/spongepowered/tools/obfuscation/SupportedOptions.java index e8f2ceef..e278faf7 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/SupportedOptions.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/SupportedOptions.java @@ -28,6 +28,10 @@ import java.util.Set; import com.google.common.collect.ImmutableSet; +/** + * Supported options for the annotation processor. Not an enum mainly so that + * the string tokens can be inlined. + */ public final class SupportedOptions { public static final String TOKENS = "tokens"; diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/TargetObfuscationEnvironment.java b/src/ap/java/org/spongepowered/tools/obfuscation/TargetObfuscationEnvironment.java index f916003e..5d420a74 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/TargetObfuscationEnvironment.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/TargetObfuscationEnvironment.java @@ -50,8 +50,18 @@ import org.spongepowered.asm.util.ObfuscationUtil; import org.spongepowered.asm.util.ObfuscationUtil.IClassRemapper; import org.spongepowered.tools.obfuscation.interfaces.IMixinAnnotationProcessor; +/** + * Stores information relevant to a particular target obfuscation environment. + * + *

We classify different types of possible obfuscation (eg. "searge", "notch" + * ) as obfuscation environments and store related information such as + * the input SRG mappings, generated refmap, generated SRGs, here.

+ */ class TargetObfuscationEnvironment { + /** + * Remapping proxy for remapping descriptors + */ final class RemapperProxy implements IClassRemapper { @Override diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/interfaces/IMixinValidator.java b/src/ap/java/org/spongepowered/tools/obfuscation/interfaces/IMixinValidator.java index 9f43e6b9..3b5488df 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/interfaces/IMixinValidator.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/interfaces/IMixinValidator.java @@ -37,6 +37,9 @@ import org.spongepowered.tools.obfuscation.TypeHandle; */ public interface IMixinValidator { + /** + * Validation pass + */ public enum ValidationPass { EARLY, LATE diff --git a/src/ap/java/org/spongepowered/tools/obfuscation/struct/Message.java b/src/ap/java/org/spongepowered/tools/obfuscation/struct/Message.java index 4c67ce92..c18cb8fc 100644 --- a/src/ap/java/org/spongepowered/tools/obfuscation/struct/Message.java +++ b/src/ap/java/org/spongepowered/tools/obfuscation/struct/Message.java @@ -30,6 +30,10 @@ import javax.lang.model.element.AnnotationValue; import javax.lang.model.element.Element; import javax.tools.Diagnostic; +/** + * Wrapper for Annotation Processor messages, used to enable messages to be + * easily queued and manipulated + */ public class Message { private Diagnostic.Kind kind; diff --git a/src/bridge/java/org/spongepowered/asm/bridge/RemapperAdapter.java b/src/bridge/java/org/spongepowered/asm/bridge/RemapperAdapter.java index 5d6e9fe8..11eae88f 100644 --- a/src/bridge/java/org/spongepowered/asm/bridge/RemapperAdapter.java +++ b/src/bridge/java/org/spongepowered/asm/bridge/RemapperAdapter.java @@ -31,6 +31,9 @@ import org.spongepowered.asm.mixin.extensibility.IRemapper; import org.spongepowered.asm.util.ObfuscationUtil; import org.spongepowered.asm.util.ObfuscationUtil.IClassRemapper; +/** + * Base impl of remapper + */ public abstract class RemapperAdapter implements IRemapper, IClassRemapper { protected final Logger logger = LogManager.getLogger("mixin"); diff --git a/src/bridge/java/org/spongepowered/asm/bridge/RemapperAdapterFML.java b/src/bridge/java/org/spongepowered/asm/bridge/RemapperAdapterFML.java index 165966cd..97750e1a 100644 --- a/src/bridge/java/org/spongepowered/asm/bridge/RemapperAdapterFML.java +++ b/src/bridge/java/org/spongepowered/asm/bridge/RemapperAdapterFML.java @@ -30,6 +30,9 @@ import java.lang.reflect.Method; import org.objectweb.asm.commons.Remapper; import org.spongepowered.asm.mixin.extensibility.IRemapper; +/** + * Remapper adapter which remaps using FML's deobfuscating remapper + */ public class RemapperAdapterFML extends RemapperAdapter { private final Method mdUnmap; diff --git a/src/main/java/org/spongepowered/asm/launch/MixinInitialisationError.java b/src/main/java/org/spongepowered/asm/launch/MixinInitialisationError.java index bc7ca989..8d32df36 100644 --- a/src/main/java/org/spongepowered/asm/launch/MixinInitialisationError.java +++ b/src/main/java/org/spongepowered/asm/launch/MixinInitialisationError.java @@ -24,6 +24,9 @@ */ package org.spongepowered.asm.launch; +/** + * Error raised when mixin subsystem initialisation fails + */ public class MixinInitialisationError extends Error { private static final long serialVersionUID = 1L; diff --git a/src/main/java/org/spongepowered/asm/mixin/MixinEnvironment.java b/src/main/java/org/spongepowered/asm/mixin/MixinEnvironment.java index 44e09374..a15760de 100644 --- a/src/main/java/org/spongepowered/asm/mixin/MixinEnvironment.java +++ b/src/main/java/org/spongepowered/asm/mixin/MixinEnvironment.java @@ -545,6 +545,9 @@ public class MixinEnvironment implements ITokenProvider { } + /** + * Temporary + */ static class MixinLogger { static MixinAppender appender = new MixinAppender("MixinLogger", null, null); @@ -555,11 +558,13 @@ public class MixinEnvironment implements ITokenProvider { log.addAppender(appender); } + /** + * Temporary + */ static class MixinAppender extends AbstractAppender { protected MixinAppender(String name, Filter filter, Layout layout) { super(name, filter, layout); - // TODO Auto-generated constructor stub } @Override diff --git a/src/main/java/org/spongepowered/asm/mixin/MixinException.java b/src/main/java/org/spongepowered/asm/mixin/MixinException.java index ef71da5d..059723c0 100644 --- a/src/main/java/org/spongepowered/asm/mixin/MixinException.java +++ b/src/main/java/org/spongepowered/asm/mixin/MixinException.java @@ -24,6 +24,9 @@ */ package org.spongepowered.asm.mixin; +/** + * Base class for all mixin processor exceptions + */ public class MixinException extends RuntimeException { private static final long serialVersionUID = 1L; diff --git a/src/main/java/org/spongepowered/asm/mixin/RemapperChain.java b/src/main/java/org/spongepowered/asm/mixin/RemapperChain.java index 117eed0b..b0aed8c0 100644 --- a/src/main/java/org/spongepowered/asm/mixin/RemapperChain.java +++ b/src/main/java/org/spongepowered/asm/mixin/RemapperChain.java @@ -29,6 +29,10 @@ import java.util.List; import org.spongepowered.asm.mixin.extensibility.IRemapper; +/** + * Mixin environment remapper chain. Contains all remappers for the current + * environment to facilitate remapping via all registered remappers. + */ public class RemapperChain implements IRemapper { private final List remappers = new ArrayList(); 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 696417c2..58005a42 100644 --- a/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/extensibility/IMixinInfo.java @@ -29,6 +29,9 @@ import java.util.List; import org.spongepowered.asm.lib.tree.ClassNode; import org.spongepowered.asm.mixin.MixinEnvironment.Phase; +/** + * Interface for MixinInfo, used in extensibility API + */ public interface IMixinInfo { /** diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/InjectionNodes.java b/src/main/java/org/spongepowered/asm/mixin/injection/InjectionNodes.java index 53229645..96fbdb1d 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/InjectionNodes.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/InjectionNodes.java @@ -29,52 +29,119 @@ import java.util.HashMap; import java.util.Map; import org.spongepowered.asm.lib.tree.AbstractInsnNode; +import org.spongepowered.asm.mixin.injection.struct.Target; import org.spongepowered.asm.util.ASMHelper; +/** + * Used to keep track of instruction nodes in a {@link Target} method which are + * targetted by various types of injector. This collection is populated during + * the first injector pass and allows injectors to keep track of their targets + * even when the target method is being manipulated by other injectors. + */ public class InjectionNodes extends ArrayList { + /** + * Never gonna give you up + */ private static final long serialVersionUID = 1L; + /** + * A node targetted by one or more injectors. Using this wrapper allows + * injectors to be aware of when their target node is removed or replace by + * another injector. It also allows injectors to decorate certain nodes with + * custom metadata to allow arbitration between injectors to take place. + */ public static class InjectionNode implements Comparable { + /** + * The original node targetted + */ private final AbstractInsnNode originalTarget; + /** + * Initially set to the {@link #originalTarget}, if an injector removes + * or replaces this node then points to the current target. Can be null + * if the node is removed. + */ private AbstractInsnNode currentTarget; + /** + * Injector decorations on this node + */ private Map decorations; - public InjectionNode(AbstractInsnNode target) { - this.currentTarget = this.originalTarget = target; + /** + * Create a new node wrapper for the specified target node + * + * @param node target node + */ + public InjectionNode(AbstractInsnNode node) { + this.currentTarget = this.originalTarget = node; } + /** + * Get the original target of this node + */ public AbstractInsnNode getOriginalTarget() { return this.originalTarget; } + /** + * Get the current target of this node, can be null if the node was + * replaced + */ public AbstractInsnNode getCurrentTarget() { return this.currentTarget; } - public void replace(AbstractInsnNode currentTarget) { - this.currentTarget = currentTarget; + /** + * Replace this node with the specified target + * + * @param target new node + */ + public void replace(AbstractInsnNode target) { + this.currentTarget = target; } + /** + * Remove the node + */ public void remove() { this.currentTarget = null; } + /** + * Checks whether the original or current target of this node match the + * specified node + * + * @param node node to check + * @return true if the supplied node matches either of this node's + * internal identities + */ public boolean matches(AbstractInsnNode node) { return this.originalTarget == node || this.currentTarget == node; } + /** + * Get whether this node has been replaced + */ public boolean isReplaced() { return this.originalTarget != this.currentTarget; } + /** + * Get whether this node has been removed + */ public boolean isRemoved() { return this.currentTarget == null; } + /** + * Decorate this node with arbitrary metadata for injector arbitration + * + * @param key meta key + * @param value meta value + */ public void decorate(K key, V value) { if (this.decorations == null) { this.decorations = new HashMap(); @@ -82,20 +149,38 @@ public class InjectionNodes extends ArrayList { this.decorations.put(key, value); } + /** + * Get whether this node is decorated with the specified key + * + * @param key meta key + * @return true if the specified decoration exists + */ public boolean hasDecoration(K key) { return this.decorations != null && this.decorations.get(key) != null; } + /** + * Get the specified decoration + * + * @param key meta key + * @return decoration value or null if absent + */ @SuppressWarnings("unchecked") public V getDecoration(K key) { return (V) (this.decorations == null ? null : this.decorations.get(key)); } + /* (non-Javadoc) + * @see java.lang.Comparable#compareTo(java.lang.Object) + */ @Override public int compareTo(InjectionNode other) { return other == null ? Integer.MAX_VALUE : this.hashCode() - other.hashCode(); } + /* (non-Javadoc) + * @see java.lang.Object#toString() + */ @Override public String toString() { return String.format("InjectionNode[%s]", ASMHelper.getNodeDescriptionForDebug(this.currentTarget)); @@ -103,6 +188,12 @@ public class InjectionNodes extends ArrayList { } + /** + * Add a tracked node to this collection if it does not already exist + * + * @param node Instruction node to add + * @return wrapper for the specified node + */ public InjectionNode add(AbstractInsnNode node) { InjectionNode injectionNode = this.get(node); if (injectionNode == null) { @@ -112,6 +203,13 @@ public class InjectionNodes extends ArrayList { return injectionNode; } + /** + * Get a tracked node from this collection if it already exists, returns + * null if the node is not tracked + * + * @param node instruction node + * @return wrapper node or null if not tracked + */ public InjectionNode get(AbstractInsnNode node) { for (InjectionNode injectionNode : this) { if (injectionNode.matches(node)) { @@ -121,10 +219,23 @@ public class InjectionNodes extends ArrayList { return null; } + /** + * Get whether this collection contains a mapping for the specified insn + * + * @param node instruction node to check + * @return true if a wrapper exists for the node + */ public boolean contains(AbstractInsnNode node) { return this.get(node) != null; } + /** + * Replace the specified node with the new node, does not update the wrapper + * if no wrapper exists for oldNode + * + * @param oldNode node being replaced + * @param newNode node to replace with + */ public void replace(AbstractInsnNode oldNode, AbstractInsnNode newNode) { InjectionNode injectionNode = this.get(oldNode); if (injectionNode != null) { @@ -132,8 +243,14 @@ public class InjectionNodes extends ArrayList { } } - public void remove(AbstractInsnNode oldNode) { - InjectionNode injectionNode = this.get(oldNode); + /** + * Mark the specified node as removed, does not update the wrapper if no + * wrapper exists + * + * @param node node being removed + */ + public void remove(AbstractInsnNode node) { + InjectionNode injectionNode = this.get(node); if (injectionNode != null) { injectionNode.remove(); } 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 84f67f18..b16c8bf4 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/InjectionPoint.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/InjectionPoint.java @@ -24,6 +24,7 @@ */ package org.spongepowered.asm.mixin.injection; +import java.lang.reflect.Array; import java.lang.reflect.Constructor; import java.util.ArrayList; import java.util.Arrays; @@ -148,12 +149,12 @@ public abstract class InjectionPoint { super(points); } + @SuppressWarnings("unchecked") @Override public boolean find(String desc, InsnList insns, Collection nodes) { boolean found = false; - @SuppressWarnings("unchecked") - ArrayList[] allNodes = new ArrayList[this.components.length]; + ArrayList[] allNodes = (ArrayList[]) Array.newInstance(ArrayList.class, this.components.length); for (int i = 0; i < this.components.length; i++) { allNodes[i] = new ArrayList(); diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/InjectionValidationException.java b/src/main/java/org/spongepowered/asm/mixin/injection/InjectionValidationException.java index 19a61b3e..8efcbd2e 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/InjectionValidationException.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/InjectionValidationException.java @@ -24,6 +24,9 @@ */ package org.spongepowered.asm.mixin.injection; +/** + * Thrown when an injector group fails an injection check + */ public class InjectionValidationException extends Exception { private static final long serialVersionUID = 1L; diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/InvalidInjectionException.java b/src/main/java/org/spongepowered/asm/mixin/injection/InvalidInjectionException.java index 3b896892..bd0517ca 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/InvalidInjectionException.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/InvalidInjectionException.java @@ -28,6 +28,10 @@ import org.spongepowered.asm.mixin.injection.struct.InjectionInfo; import org.spongepowered.asm.mixin.transformer.InvalidMixinException; import org.spongepowered.asm.mixin.transformer.MixinTargetContext; +/** + * Thrown when an injector fails a state check, for example if an injector + * handler signature is invalid, an invalid opcode is targetted, etc. + */ public class InvalidInjectionException extends InvalidMixinException { private static final long serialVersionUID = 1L; diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/callback/CancellationException.java b/src/main/java/org/spongepowered/asm/mixin/injection/callback/CancellationException.java index d9fdcb10..c2c27639 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/callback/CancellationException.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/callback/CancellationException.java @@ -24,6 +24,10 @@ */ package org.spongepowered.asm.mixin.injection.callback; +/** + * Exception thrown when a consumer attemtps to call cancel() on a + * callback not marked as cancellable. + */ public class CancellationException extends RuntimeException { private static final long serialVersionUID = 1L; diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/modify/InvalidImplicitDiscriminatorException.java b/src/main/java/org/spongepowered/asm/mixin/injection/modify/InvalidImplicitDiscriminatorException.java index 733103ff..8a0a7ac4 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/modify/InvalidImplicitDiscriminatorException.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/modify/InvalidImplicitDiscriminatorException.java @@ -26,6 +26,10 @@ package org.spongepowered.asm.mixin.injection.modify; import org.spongepowered.asm.mixin.MixinException; +/** + * Thrown when an implicit discriminator (no args) fails to identify + * a unique candidate. + */ public class InvalidImplicitDiscriminatorException extends MixinException { private static final long serialVersionUID = 1L; diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/struct/CallbackInjectionInfo.java b/src/main/java/org/spongepowered/asm/mixin/injection/struct/CallbackInjectionInfo.java index 313a55f7..4e671147 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/struct/CallbackInjectionInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/struct/CallbackInjectionInfo.java @@ -26,12 +26,16 @@ package org.spongepowered.asm.mixin.injection.struct; import org.spongepowered.asm.lib.tree.AnnotationNode; import org.spongepowered.asm.lib.tree.MethodNode; +import org.spongepowered.asm.mixin.injection.Inject; import org.spongepowered.asm.mixin.injection.callback.CallbackInjector; import org.spongepowered.asm.mixin.injection.callback.LocalCapture; import org.spongepowered.asm.mixin.injection.code.Injector; import org.spongepowered.asm.mixin.transformer.MixinTargetContext; import org.spongepowered.asm.util.ASMHelper; +/** + * Information about a callback to inject, usually specified by {@link Inject} + */ public class CallbackInjectionInfo extends InjectionInfo { protected CallbackInjectionInfo(MixinTargetContext mixin, MethodNode method, AnnotationNode annotation) { diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/struct/InvalidMemberDescriptorException.java b/src/main/java/org/spongepowered/asm/mixin/injection/struct/InvalidMemberDescriptorException.java index 44bff320..899eecb0 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/struct/InvalidMemberDescriptorException.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/struct/InvalidMemberDescriptorException.java @@ -26,6 +26,9 @@ package org.spongepowered.asm.mixin.injection.struct; import org.spongepowered.asm.mixin.MixinException; +/** + * Thrown when a {@link MemberInfo} fails basic syntax validation + */ public class InvalidMemberDescriptorException extends MixinException { private static final long serialVersionUID = 1L; diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/struct/ModifyArgInjectionInfo.java b/src/main/java/org/spongepowered/asm/mixin/injection/struct/ModifyArgInjectionInfo.java index 5b0ab5cd..bc90793d 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/struct/ModifyArgInjectionInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/struct/ModifyArgInjectionInfo.java @@ -26,11 +26,15 @@ package org.spongepowered.asm.mixin.injection.struct; import org.spongepowered.asm.lib.tree.AnnotationNode; import org.spongepowered.asm.lib.tree.MethodNode; +import org.spongepowered.asm.mixin.injection.ModifyArg; import org.spongepowered.asm.mixin.injection.code.Injector; import org.spongepowered.asm.mixin.injection.invoke.ModifyArgInjector; import org.spongepowered.asm.mixin.transformer.MixinTargetContext; import org.spongepowered.asm.util.ASMHelper; +/** + * Information about a {@link ModifyArg} injector + */ public class ModifyArgInjectionInfo extends InjectionInfo { public ModifyArgInjectionInfo(MixinTargetContext mixin, MethodNode method, AnnotationNode annotation) { diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/struct/ModifyVariableInjectionInfo.java b/src/main/java/org/spongepowered/asm/mixin/injection/struct/ModifyVariableInjectionInfo.java index cd841cd0..048622b0 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/struct/ModifyVariableInjectionInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/struct/ModifyVariableInjectionInfo.java @@ -26,12 +26,16 @@ package org.spongepowered.asm.mixin.injection.struct; import org.spongepowered.asm.lib.tree.AnnotationNode; import org.spongepowered.asm.lib.tree.MethodNode; +import org.spongepowered.asm.mixin.injection.ModifyVariable; import org.spongepowered.asm.mixin.injection.code.Injector; import org.spongepowered.asm.mixin.injection.modify.LocalVariableDiscriminator; import org.spongepowered.asm.mixin.injection.modify.ModifyVariableInjector; import org.spongepowered.asm.mixin.transformer.MixinTargetContext; import org.spongepowered.asm.util.ASMHelper; +/** + * Information about a {@link ModifyVariable} injector + */ public class ModifyVariableInjectionInfo extends InjectionInfo { public ModifyVariableInjectionInfo(MixinTargetContext mixin, MethodNode method, AnnotationNode annotation) { diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/struct/RedirectInjectionInfo.java b/src/main/java/org/spongepowered/asm/mixin/injection/struct/RedirectInjectionInfo.java index e3396041..d56531c8 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/struct/RedirectInjectionInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/struct/RedirectInjectionInfo.java @@ -30,6 +30,9 @@ import org.spongepowered.asm.mixin.injection.code.Injector; import org.spongepowered.asm.mixin.injection.invoke.RedirectInjector; import org.spongepowered.asm.mixin.transformer.MixinTargetContext; +/** + * Information about a redirector injector + */ public class RedirectInjectionInfo extends InjectionInfo { public RedirectInjectionInfo(MixinTargetContext mixin, MethodNode method, AnnotationNode annotation) { diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/struct/ReferenceMapper.java b/src/main/java/org/spongepowered/asm/mixin/injection/struct/ReferenceMapper.java index d06e2bc2..65b1485b 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/struct/ReferenceMapper.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/struct/ReferenceMapper.java @@ -37,42 +37,107 @@ import com.google.gson.GsonBuilder; import net.minecraft.launchwrapper.Launch; +/** + * Stores runtime information allowing field, method and type references which + * cannot be hard remapped by the reobfuscation process to be remapped in a + * "soft" manner at runtime. Refmaps are generated by the Annotation + * Processor at compile time and must be bundled with an obfuscated binary + * to allow obfuscated references in injectors and other String-defined targets + * to be remapped to the target obfsucation environment as appropriate. If the + * refmap is absent the environment is assumed to be deobfuscated (eg. dev-time) + * and injections and other transformations will fail if this is not the case. + */ public final class ReferenceMapper implements Serializable { private static final long serialVersionUID = 2L; + /** + * Resource to attempt to load if no source is specified explicitly + */ public static final String DEFAULT_RESOURCE = "mixin.refmap.json"; + /** + * Passthrough mapper, used as failover + */ public static final ReferenceMapper DEFAULT_MAPPER = new ReferenceMapper(true); + /** + * "Default" mappings. The set of mappings to use as "default" is specified + * by the AP. Each entry is keyed by the owning mixin, with the value map + * containing the actual remappings for each owner + */ private final Map> mappings = Maps.newHashMap(); + /** + * All mapping sets, keyed by environment type, eg. "notch", "searge". The + * format of each map within this map is the same as for {@link #mappings} + */ private final Map>> data = Maps.newHashMap(); + /** + * True if this refmap cannot be written. Only true for the + * {@link #DEFAULT_MAPPER} + */ private final transient boolean readOnly; + /** + * Current remapping context, used as the key into {@link data} + */ private transient String context = null; + /** + * Create an empty refmap + */ public ReferenceMapper() { this(false); } + /** + * Create a readonly refmap, only used by {@link #DEFAULT_MAPPER} + * + * @param readOnly flag to indicate read-only + */ private ReferenceMapper(boolean readOnly) { this.readOnly = readOnly; } + /** + * Get the current context + * + * @return current context key, can be null + */ public String getContext() { return this.context; } + /** + * Set the current remap context, can be null + * + * @param context remap context + */ public void setContext(String context) { this.context = context; } + /** + * Remap a reference for the specified owning class in the current context + * + * @param className Owner class + * @param reference Reference to remap + * @return remapped reference, returns original reference if not remapped + */ public String remap(String className, String reference) { return this.remapWithContext(this.context, className, reference); } + /** + * Remap a reference for the specified owning class in the specified context + * + * @param context Remap context to use + * @param className Owner class + * @param reference Reference to remap + * @return remapped reference, returns original reference if not remapped + */ public String remapWithContext(String context, String className, String reference) { Map> mappings = this.mappings; if (context != null) { @@ -84,6 +149,9 @@ public final class ReferenceMapper implements Serializable { return this.remap(mappings, className, reference); } + /** + * Remap the things + */ private String remap(Map> mappings, String className, String reference) { if (className == null) { for (Map mapping : mappings.values()) { @@ -101,8 +169,16 @@ public final class ReferenceMapper implements Serializable { return remappedReference != null ? remappedReference : reference; } + /** + * Add a mapping to this refmap + * + * @param context Obfuscation context, can be null + * @param className Class which owns this mapping, cannot be null + * @param reference Reference to remap, cannot be null + * @param newReference Remapped value, cannot be null + */ public void addMapping(String context, String className, String reference, String newReference) { - if (this.readOnly) { + if (this.readOnly || reference == null || newReference == null || reference.equals(newReference)) { return; } Map> mappings = this.mappings; @@ -121,10 +197,21 @@ public final class ReferenceMapper implements Serializable { classMappings.put(reference, newReference); } + /** + * Write this refmap out to the specified writer + * + * @param writer Writer to write to + */ public void write(Appendable writer) { new GsonBuilder().setPrettyPrinting().create().toJson(this, writer); } + /** + * Read a new refmap from the specified resource + * + * @param resource Resource to read from + * @return new refmap or {@link #DEFAULT_MAPPER} if reading fails + */ public static ReferenceMapper read(String resource) { Reader reader = null; try { @@ -143,7 +230,18 @@ public final class ReferenceMapper implements Serializable { } } + /** + * Read a new refmap instance from the specified reader + * + * @param reader Reader to read from + * @return new refmap + */ public static ReferenceMapper read(Reader reader) { - return new Gson().fromJson(reader, ReferenceMapper.class); + try { + return new Gson().fromJson(reader, ReferenceMapper.class); + } catch (Exception ex) { + return ReferenceMapper.DEFAULT_MAPPER; + } } + } diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/ClassInfo.java b/src/main/java/org/spongepowered/asm/mixin/transformer/ClassInfo.java index fd25c807..269cb0e0 100644 --- a/src/main/java/org/spongepowered/asm/mixin/transformer/ClassInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/transformer/ClassInfo.java @@ -156,6 +156,9 @@ public class ClassInfo extends TreeInfo { */ abstract static class Member { + /** + * Member type + */ static enum Type { METHOD, FIELD diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/InvalidMixinException.java b/src/main/java/org/spongepowered/asm/mixin/transformer/InvalidMixinException.java index c726fc63..447285be 100644 --- a/src/main/java/org/spongepowered/asm/mixin/transformer/InvalidMixinException.java +++ b/src/main/java/org/spongepowered/asm/mixin/transformer/InvalidMixinException.java @@ -26,6 +26,9 @@ package org.spongepowered.asm.mixin.transformer; import org.spongepowered.asm.mixin.MixinException; +/** + * Thrown by the mixin validator when a mixin fails a pre-flight check + */ public class InvalidMixinException extends MixinException { private static final long serialVersionUID = 1L; diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinTransformerModuleCheckClass.java b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinTransformerModuleCheckClass.java index bd9cf76a..4240a8e8 100644 --- a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinTransformerModuleCheckClass.java +++ b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinTransformerModuleCheckClass.java @@ -34,6 +34,9 @@ import org.spongepowered.asm.mixin.MixinException; */ public class MixinTransformerModuleCheckClass implements IMixinTransformerModule { + /** + * Exception thrown when checkclass fails + */ public static class ValidationFailedException extends MixinException { private static final long serialVersionUID = 1L; diff --git a/src/main/java/org/spongepowered/asm/obfuscation/SrgField.java b/src/main/java/org/spongepowered/asm/obfuscation/SrgField.java index 77b747d9..30f25b4f 100644 --- a/src/main/java/org/spongepowered/asm/obfuscation/SrgField.java +++ b/src/main/java/org/spongepowered/asm/obfuscation/SrgField.java @@ -26,6 +26,9 @@ package org.spongepowered.asm.obfuscation; import com.google.common.base.Objects; +/** + * Stores information about an SRG field mapping during AP runs + */ public final class SrgField { private final String mapping; diff --git a/src/main/java/org/spongepowered/asm/obfuscation/SrgMethod.java b/src/main/java/org/spongepowered/asm/obfuscation/SrgMethod.java index f214129e..f0a9d8f6 100644 --- a/src/main/java/org/spongepowered/asm/obfuscation/SrgMethod.java +++ b/src/main/java/org/spongepowered/asm/obfuscation/SrgMethod.java @@ -26,6 +26,9 @@ package org.spongepowered.asm.obfuscation; import com.google.common.base.Objects; +/** + * Stores information about an SRG method mapping during AP runs + */ public final class SrgMethod { private final String name; diff --git a/src/main/java/org/spongepowered/asm/util/ASMHelper.java b/src/main/java/org/spongepowered/asm/util/ASMHelper.java index 7d08b138..de2bfcab 100644 --- a/src/main/java/org/spongepowered/asm/util/ASMHelper.java +++ b/src/main/java/org/spongepowered/asm/util/ASMHelper.java @@ -41,6 +41,9 @@ import org.spongepowered.asm.lib.Type; import org.spongepowered.asm.lib.tree.*; import org.spongepowered.asm.lib.util.CheckClassAdapter; +/** + * Utility methods for working with ASM + */ public class ASMHelper { private static final int[] intConstants = new int[] diff --git a/src/main/java/org/spongepowered/asm/util/LVTGeneratorException.java b/src/main/java/org/spongepowered/asm/util/LVTGeneratorException.java index f6ba9af5..a9bc5348 100644 --- a/src/main/java/org/spongepowered/asm/util/LVTGeneratorException.java +++ b/src/main/java/org/spongepowered/asm/util/LVTGeneratorException.java @@ -26,6 +26,10 @@ package org.spongepowered.asm.util; import org.spongepowered.asm.mixin.MixinException; +/** + * Exception thrown when something goes horribly wrong whilst summoning the + * antichrist generating the LVT for a target method. + */ public class LVTGeneratorException extends MixinException { private static final long serialVersionUID = 1L; diff --git a/src/main/java/org/spongepowered/asm/util/ObfuscationUtil.java b/src/main/java/org/spongepowered/asm/util/ObfuscationUtil.java index ee990ccd..5dc69656 100644 --- a/src/main/java/org/spongepowered/asm/util/ObfuscationUtil.java +++ b/src/main/java/org/spongepowered/asm/util/ObfuscationUtil.java @@ -24,8 +24,14 @@ */ package org.spongepowered.asm.util; +/** + * Utility methods for obfuscation tasks + */ public abstract class ObfuscationUtil { + /** + * Interface for remapper proxies + */ public interface IClassRemapper { /** diff --git a/src/main/java/org/spongepowered/asm/util/PrettyPrinter.java b/src/main/java/org/spongepowered/asm/util/PrettyPrinter.java index de2c5432..67f08ac0 100644 --- a/src/main/java/org/spongepowered/asm/util/PrettyPrinter.java +++ b/src/main/java/org/spongepowered/asm/util/PrettyPrinter.java @@ -40,8 +40,16 @@ import com.google.common.base.Strings; */ public class PrettyPrinter { + /** + * Interface for object which supports printing to pretty printer + */ public interface IPrettyPrintable { + /** + * Append this objec to specified pretty printer + * + * @param printer printer to append to + */ public abstract void print(PrettyPrinter printer); }