Fixing javadoc issues

springloaded/src/main/java/org/springsource/loaded/ExecutorBuilder.java

@@ -40,7 +40,7 @@ import org.objectweb.asm.Opcodes;
  * can be accessed through reflection).
  * <p>
  * <b>Constructors</b>. Constructors are added to the executor as ___init___ methods, with the invokespecials within them
- * transformed, either removed if they are calls to Object.<init> or mutated into ___init___ calls on the supertype instance.
+ * transformed, either removed if they are calls to Object.&lt;init&gt; or mutated into ___init___ calls on the supertype instance.
  * 
  * @author Andy Clement
  * @since 0.5.0

springloaded/src/main/java/org/springsource/loaded/FieldReaderWriter.java

@@ -55,7 +55,7 @@ public class FieldReaderWriter {
 	 * 
 	 * @param instance the object instance upon which to set the field
 	 * @param newValue the new value for that field
-	 * @param the optional state manager for this instance, which will be looked up (expensive) if not passed in
+	 * @param stateManager the optional state manager for this instance, which will be looked up (expensive) if not passed in
 	 */
 	public void setValue(Object instance, Object newValue, ISMgr stateManager) throws IllegalAccessException {
 		if (typeDescriptor.isReloadable()) {

springloaded/src/main/java/org/springsource/loaded/InterfaceExtractor.java

@@ -28,17 +28,17 @@ import org.objectweb.asm.MethodVisitor;
  * methods in the interface is that they contain an extra (leading) parameter that is the type of the original loaded class.<br>
  * For example:<br>
  * 
- * <tt> <pre>
+ * <pre><tt>
  * class Foo {
- * public String foo(int i) {}
+ *   public String foo(int i) {}
  * }
- * </pre></tt>
+ * </tt></pre>
  * 
  * will cause creation of an interface method:
  * 
- * <tt> <pre>
+ * <pre> <tt>
  * String foo(Foo instance, int i) {}
- * </pre></tt>
+ * </tt></pre>
  * 
  * @author Andy Clement
  * @since 0.5.0

springloaded/src/main/java/org/springsource/loaded/LoadtimeInstrumentationPlugin.java

@@ -35,7 +35,7 @@ public interface LoadtimeInstrumentationPlugin extends Plugin {
 	 * 
 	 * @param slashedTypeName the type name, slashed form (e.g. java/lang/String)
 	 * @param classLoader the classloader loading the type
-	 * @param protectionDomain
+	 * @param protectionDomain the ProtectionDomain for the class represented by the bytes
 	 * @param bytes the classfile contents for the type
 	 * @return true if this plugin wants to change the bytes for the named type
 	 */
@@ -44,7 +44,7 @@ public interface LoadtimeInstrumentationPlugin extends Plugin {
 	/**
 	 * Once accept has returned true for a type, the modify method will be called to make the actual change to the classfile bytes.
 	 * 
-	 * @param slashedTypeName the type name, slashed form (e.g. java/lang/String)
+	 * @param slashedClassName the class name, slashed form (e.g. java/lang/String)
 	 * @param classLoader the classloader loading the type
 	 * @param bytes the classfile contents for the type
 	 * @return the new (modified) bytes for the class

springloaded/src/main/java/org/springsource/loaded/PrefixTypePattern.java

@@ -26,11 +26,10 @@ public class PrefixTypePattern extends TypePattern {
 	private String pattern;
 
 	/**
-	 * @param prefix prefix of the form 'com.foo.bar..*'
+	 * @param pattern the prefix pattern of the form 'com.foo.bar..*'
 	 */
 	public PrefixTypePattern(String pattern) {
-		this.pattern = pattern.substring(0, pattern.length() - 2); // chop off
-																	// the '.*'
+		this.pattern = pattern.substring(0, pattern.length() - 2); // chop off the '.*'
 	}
 
 	protected boolean internalMatches(String input) {

springloaded/src/main/java/org/springsource/loaded/RTH.java

@@ -30,9 +30,12 @@ public class RTH {
 
 	/**
 	 * Collapse a String and int into an array
+	 * 
+	 * @param aString some string
+	 * @param anInt some int
 	 */
-	public static Object[] collapse(String arg0, int arg1) {
-		return new Object[] { arg0, Integer.valueOf(arg1) };
+	public static Object[] collapse(String aString, int anInt) {
+		return new Object[] { aString, Integer.valueOf(anInt) };
 	}
 
 }

springloaded/src/main/java/org/springsource/loaded/ReloadableType.java

@@ -172,6 +172,10 @@ public class ReloadableType {
 	/**
 	 * Gets the 'orignal' method corresponding to given name and method descriptor. This only considers methods that exist in the
 	 * first (non-reloaded) version of the type.
+	 * 
+	 * @param name method name
+	 * @param descriptor method descriptor (e.g (Ljava/lang/String;)I)
+	 * @return the MethodMember or an exception if not found
 	 */
 	// TODO introduce a cache for people trolling through the methods array? same for fields?
 	public MethodMember getMethod(String name, String descriptor) {
@@ -270,6 +274,9 @@ public class ReloadableType {
 
 	/**
 	 * Load a new version of this type, using the specified suffix to tag the newly generated artifact class names.
+	 * 
+	 * @param versionsuffix the String suffix to append to classnames being created for the reloaded class
+	 * @param newbytedata the class bytes for the new version of this class
 	 */
 	public boolean loadNewVersion(String versionsuffix, byte[] newbytedata) {
 		javaMethodCache = null;
@@ -742,6 +749,11 @@ public class ReloadableType {
 	/**
 	 * Gets the method corresponding to given name and descriptor, taking into consideration changes that have happened by
 	 * reloading.
+	 * 
+	 * @param name the member name
+	 * @param descriptor the member descriptor (e.g. (Ljava/lang/String;)I)
+	 * @return the MethodMember for that name and descriptor. Null if not found on a live version, or an exception if there is no live version and
+	 * it cannot be found.
 	 */
 	public MethodMember getCurrentMethod(String name, String descriptor) {
 		if (liveVersion == null) {
@@ -1186,7 +1198,7 @@ public class ReloadableType {
 	 * 
 	 * @param instance the object upon which to set the field (maybe null for static fields)
 	 * @param fieldname the name of the field
-	 * @param
+	 * @param isStatic whether the field is static
 	 * @param newValue the new value to put into the field
 	 */
 	public void setField(Object instance, String fieldname, boolean isStatic, Object newValue) throws IllegalAccessException {
@@ -1219,8 +1231,7 @@ public class ReloadableType {
 	 * 
 	 * @param instance the object upon which to set the field (maybe null for static fields)
 	 * @param fieldname the name of the field
-	 * @param
-	 * @param newValue the new value to put into the field
+	 * @param isStatic whether the field is static or not
 	 */
 	public Object getField(Object instance, String fieldname, boolean isStatic) throws IllegalAccessException {
 		FieldReaderWriter fieldReaderWriter = locateField(fieldname);

springloaded/src/main/java/org/springsource/loaded/SystemClassReflectionRewriter.java

@@ -47,6 +47,7 @@ import org.objectweb.asm.Opcodes;
  * <li>getDeclaredConstructor
  * <li>getDeclaredMethods
  * <li>getDeclaredMethod</li>
+ * </ul>
  * <p>
  * Due to ProxyGenerator
  * <ul>

springloaded/src/main/java/org/springsource/loaded/TypeRegistry.java

@@ -889,7 +889,7 @@ public class TypeRegistry {
 	/**
 	 * Add a type to the registry. The name should have already passed the isReloadableTypeName() test.
 	 * 
-	 * @param dottedtypename type name of the form a.b.c.D
+	 * @param dottedname type name of the form a.b.c.D
 	 * @param initialbytes the first version of the bytes as loaded
 	 * @return the ReloadableType or null if it cannot be made reloadable
 	 */
@@ -988,6 +988,9 @@ public class TypeRegistry {
 	/**
 	 * Sometimes we discover the reloadabletype during program execution, for example A calls B and we haven't yet seen B. We find B
 	 * has been loaded by a parent classloader, let's remember B here so we can do fast lookups for it.
+	 * 
+	 * @param typeId the id for the type
+	 * @param rtype the ReloadableType to associate with the id
 	 */
 	public void rememberReloadableType(int typeId, ReloadableType rtype) {
 		if (typeId >= reloadableTypes.length) {
@@ -1002,9 +1005,12 @@ public class TypeRegistry {
 	/**
 	 * Determine the reloadabletype object representation for a specified class. If the caller already knows the ID for the type,
 	 * that would be a quicker way to locate the reloadable type object.
+	 * 
+	 * @param slashedClassName the slashed (e.g. java/lang/String) class name
+	 * @return the ReloadableType
 	 */
-	public ReloadableType getReloadableType(String slashedClassname) {
-		int id = getTypeIdFor(slashedClassname, true);
+	public ReloadableType getReloadableType(String slashedClassName) {
+		int id = getTypeIdFor(slashedClassName, true);
 		if (id >= reloadableTypesSize) {
 			return null;
 		}
@@ -1053,9 +1059,9 @@ public class TypeRegistry {
 	 * allocated for this classname if it hasn't previously been seen before. This method does not create new ReloadableType
 	 * objects, they are expected to come into existence when defined by the classloader.
 	 * 
-	 * @param slashedClassname
-	 * @param allocateIdIfNotYetLoaded
-	 * @return
+	 * @param slashedClassname the slashed class name (e.g. java/lang/String)
+	 * @param allocateIdIfNotYetLoaded if true an id will be allocated because sometime later the type will be loaded (and made reloadable)
+	 * @return the ReloadableType discovered or allocated, or null if not found and !allocateIdIfNotYetLoaded
 	 */
 	public ReloadableType getReloadableType(String slashedClassname, boolean allocateIdIfNotYetLoaded) {
 		if (allocateIdIfNotYetLoaded) {
@@ -1072,7 +1078,7 @@ public class TypeRegistry {
 	}
 
 	/**
-	 * @param name dotted name
+	 * @param name dotted name (e.g. java.lang.String)
 	 * @param bytes bytes for the class
 	 * @param permanent determines if the type should be defined in the classloader attached to this registry or in the child
 	 *        classloader that can periodically by discarded
@@ -1145,6 +1151,10 @@ public class TypeRegistry {
 	 * Determine if something has changed in a particular type related to a particular descriptor and so the dispatcher interface
 	 * should be used. The type registry ID and class ID are merged in the 'ids' parameter. This method is for INVOKESTATIC rewrites
 	 * and so performs additional checks because it assumes the target is static.
+	 * 
+	 * @param ids packed representation of the registryId (top 16bits) and typeId (bottom 16bits)
+	 * @param nameAndDescriptor the name and descriptor of the method about to be INVOKESTATIC'd
+	 * @return null if the original code can run otherwise return the dispatcher to use
 	 */
 	@UsedByGeneratedCode
 	public static Object istcheck(int ids, String nameAndDescriptor) {
@@ -1270,6 +1280,11 @@ public class TypeRegistry {
 	/**
 	 * See notes.md#001
 	 * 
+	 * @param instance the object instance on which the INVOKEINTERFACE is being called
+	 * @param params the parameters to the INVOKEINTERFACE call
+	 * @param instance2 the object instance on which the INVOKEINTERFACE is being called
+	 * @param nameAndDescriptor the name and descriptor of what is being called (e.g. foo(Ljava/lang/String)I)
+	 * @return the result of making the INVOKEINTERFACE call
 	 */
 	public static Object iiIntercept(Object instance, Object[] params, Object instance2, String nameAndDescriptor) {
 		Class<?> clazz= instance.getClass();
@@ -1349,6 +1364,10 @@ public class TypeRegistry {
 	 * everything that the descriptor embodies everything about a method interface. Therefore, if something changes about the
 	 * descriptor it is considered an entirely different method (and the old form is a deleted method). For this reason there is no
 	 * need to consider 'changed' methods, because the static-ness nor visibility cannot change.
+	 * 
+	 * @param ids packed representation of the registryId (top 16bits) and typeId (bottom 16bits)
+	 * @param nameAndDescriptor the name and descriptor of the method about to be INVOKEINTERFACE'd
+	 * @return true if the original method operation must be intercepted
 	 */
 	@UsedByGeneratedCode
 	public static boolean iincheck(int ids, String nameAndDescriptor) {
@@ -1470,6 +1489,9 @@ public class TypeRegistry {
 	/**
 	 * Called for a field operation - trying to determine whether a particular field needs special handling.
 	 * 
+	 * @param ids packed representation of the registryId (top 16bits) and typeId (bottom 16bits)
+	 * @param name the name of the instance field about to be accessed
+	 * @return true if the field operation must be intercepted
 	 */
 	@UsedByGeneratedCode
 	public static boolean instanceFieldInterceptionRequired(int ids, String name) {
@@ -1491,6 +1513,10 @@ public class TypeRegistry {
 
 	/**
 	 * Called for a field operation - trying to determine whether a particular field needs special handling.
+	 *
+	 * @param ids packed representation of the registryId (top 16bits) and typeId (bottom 16bits)
+	 * @param name the name of the static field about to be accessed
+	 * @return true if the field operation must be intercepted
 	 */
 	@UsedByGeneratedCode
 	public static boolean staticFieldInterceptionRequired(int ids, String name) {
@@ -1527,6 +1553,10 @@ public class TypeRegistry {
 	 * 
 	 * This method will return FALSE if nothing has changed to interfere with the invocation and it should proceed. This method will
 	 * return TRUE if something has changed and the caller needs to do something different.
+	 *
+	 * @param ids packed representation of the registryId (top 16bits) and typeId (bottom 16bits)
+	 * @param nameAndDescriptor the name and descriptor of the method about to be INVOKEVIRTUAL'd
+	 * @return true if the original method operation must be intercepted
 	 */
 	@UsedByGeneratedCode
 	public static boolean ivicheck(int ids, String nameAndDescriptor) {
@@ -1605,6 +1635,10 @@ public class TypeRegistry {
 
 	/**
 	 * This method discovers the reloadable type instance for the registry and type id specified.
+	 * 
+	 * @param typeRegistryId the type registry id
+	 * @param typeId the type id
+	 * @return the ReloadableType (if there is no ReloadableType an exception will be thrown) 
 	 */
 	@UsedByGeneratedCode
 	public static ReloadableType getReloadableType(int typeRegistryId, int typeId) {
@@ -1836,6 +1870,8 @@ public class TypeRegistry {
 	/**
 	 * To avoid leaking permgen we want to periodically discard the child classloader and recreate a new one. We will need to then
 	 * redefine types again over time as they are used (the most recent variants of them).
+	 * 
+	 * @param currentlyDefining the reloadable type currently being defined reloaded
 	 */
 	public void checkChildClassLoader(ReloadableType currentlyDefining) {
 		ChildClassLoader ccl = childClassLoader == null ? null : childClassLoader.get();

springloaded/src/main/java/org/springsource/loaded/Utils.java

@@ -89,7 +89,7 @@ public class Utils implements Opcodes, Constants {
 	/**
 	 * Decode a base62 encoded string into a number (base10). (More expensive than encoding)
 	 * 
-	 * @param the string to decode
+	 * @param s the string to decode
 	 * @return the number
 	 */
 	public static long decode(String s) {
@@ -607,6 +607,10 @@ public class Utils implements Opcodes, Constants {
 	/**
 	 * Given a method descriptor, extract the parameter descriptor and convert into corresponding Class objects. This requires a
 	 * reference to a class loader to convert type names into Class objects.
+	 * 
+	 * @param methodDescriptor a method descriptor (e.g (Ljava/lang/String;)I)
+	 * @param classLoader a class loader that can be used to lookup types
+	 * @return an array for classes representing the types in the method descriptor
 	 */
 	public static Class<?>[] toParamClasses(String methodDescriptor, ClassLoader classLoader) throws ClassNotFoundException {
 		Type[] paramTypes = Type.getArgumentTypes(methodDescriptor);
@@ -620,6 +624,10 @@ public class Utils implements Opcodes, Constants {
 	/**
 	 * Convert an asm Type into a corresponding Class object, requires a reference to a ClassLoader to be able to convert classnames
 	 * to class objects.
+	 * 
+	 * @param type the asm Type
+	 * @param classLoader a class loader that can be used to find types
+	 * @return the JVM Class for the type
 	 */
 	public static Class<?> toClass(Type type, ClassLoader classLoader) throws ClassNotFoundException {
 		switch (type.getSort()) {
@@ -839,6 +847,10 @@ public class Utils implements Opcodes, Constants {
 	/**
 	 * Generate the name for the executor class. Must use '$' so that it is considered by some code (eclipse debugger for example)
 	 * to be an inner type of the original class (thus able to consider itself as being from the same source file).
+	 * 
+	 * @param name the name prefix for the executor class
+	 * @param versionstamp the suffix string for the executor class name
+	 * @return an executor class name
 	 */
 	public static String getExecutorName(String name, String versionstamp) {
 		StringBuilder s = new StringBuilder(name);
@@ -1407,6 +1419,10 @@ public class Utils implements Opcodes, Constants {
 
 	/**
 	 * Utility method similar to Java 1.6 Arrays.copyOf, used instead of that method to stick to Java 1.5 only API.
+	 * 
+	 * @param array the array to copy
+	 * @param newSize the size of the new array
+	 * @return a new array of the specified size containing the supplied array elements at the beginning
 	 */
 	public static <T> T[] arrayCopyOf(T[] array, int newSize) {
 		@SuppressWarnings("unchecked")
@@ -1417,6 +1433,8 @@ public class Utils implements Opcodes, Constants {
 
 	/**
 	 * Modify visibility to be public.
+	 * @param access existing access
+	 * @return modified access, adjusted to public non-final
 	 */
 	public static int makePublicNonFinal(int access) {
 		access = (access & ~(ACC_PRIVATE | ACC_PROTECTED)) | ACC_PUBLIC;
@@ -1503,6 +1521,7 @@ public class Utils implements Opcodes, Constants {
 	 * When this happens we will default the value for the new field and forget the one we were holding onto. note: array forms are
 	 * not compatible (e.g. int[] and Integer[])
 	 * 
+	 * @param registry the type registry that can be quizzed for type information
 	 * @param result the result we have discovered and are about to return - this is never null
 	 * @param expectedTypeDescriptor the type we are looking for (will be primitive or Ljava/lang/String style)
 	 * @return the result we can return, or null if it is not compatible
@@ -1651,9 +1670,12 @@ public class Utils implements Opcodes, Constants {
 	/**
 	 * Looks at the supplied descriptor and inserts enough pops to remove all parameters. Should be used when about to avoid a
 	 * method call.
+	 * 
+	 * @param mv the method visitor to append instructions to
+	 * @param desc the method descriptor for the parameter sequence (e.g. (Ljava/lang/String;IZZ)V)
+	 * @return number of parameters popped
 	 */
 	public static int insertPopsForAllParameters(MethodVisitor mv, String desc) {
-		// Descriptor is of the format (Ljava/lang/String;IZZ)V
 		String descSequence = Utils.getParamSequence(desc);
 		if (descSequence == null) {
 			return 0; // nothing to do, there are no parameters
@@ -1674,7 +1696,6 @@ public class Utils implements Opcodes, Constants {
 			case 'J': // long - double slot
 			case 'D': // double - double slot
 				mv.visitInsn(POP2);
-				//				mv.visitInsn(POP);
 				break;
 			default:
 				throw new IllegalStateException("Unexpected character: " + ch + " from " + desc + ":" + dpos);

springloaded/src/main/java/org/springsource/loaded/agent/CglibPluginCapturing.java

@@ -112,10 +112,8 @@ public class CglibPluginCapturing extends ClassVisitor implements Constants {
 	 * because they may be either calling something that disappears on a later reload (so need to fail appropriately) or calling
 	 * something that isnt there on the first load - in this latter case they are changed to route the dynamic executor method.
 	 * 
-	 * @param classloader
-	 * @param name
-	 * @param bytes
-	 * @return
+	 * @param a the GeneratorStrategy being used
+	 * @param b the AbstractClassGenerator
 	 */
 	public static void record(Object a, Object b) {
 		// a is a Lnet/sf/cglib/core/GeneratorStrategy;

springloaded/src/main/java/org/springsource/loaded/agent/ClassPreProcessorAgentAdapter.java

@@ -57,7 +57,7 @@ public class ClassPreProcessorAgentAdapter implements ClassFileTransformer {
 	 * @param loader the defining class loader
 	 * @param className the name of class being loaded
 	 * @param classBeingRedefined when hotswap is called
-	 * @param protectionDomain
+	 * @param protectionDomain the ProtectionDomain for the class represented by the bytes
 	 * @param bytes the bytecode before weaving
 	 * @return the weaved bytecode
 	 */

springloaded/src/main/java/org/springsource/loaded/agent/ModifyDefineInClassLoaderForClassArtifactsType.java

@@ -25,6 +25,7 @@ import org.springsource.loaded.TypeRegistry;
 
 
 /**
+ * Related to the groovy support, this modifies a piece of the groovy runtime so SpringLoaded can be in the mix.
  * 
  * @author Andy Clement
  * @since 0.7.3
@@ -67,18 +68,12 @@ public class ModifyDefineInClassLoaderForClassArtifactsType extends ClassVisitor
 	}
 
 	/**
-	 * The classloader for class artifacts is used to load the generated classes for call sites. We need to rewrite these classes
+	 * The classloader for class artifacts (org/codehaus/groovy/reflection/ClassLoaderForClassArtifacts) is used to load the 
+	 * generated classes for call sites. We need to rewrite these classes
 	 * because they may be either calling something that disappears on a later reload (so need to fail appropriately) or calling
-	 * something that isnt there on the first load - in this latter case they are changed to route the dynamic executor method.
-	 * 
-	 * @param classloader
-	 * @param name
-	 * @param bytes
-	 * @return
+	 * something that is not there on the first load - in this latter case they are changed to route the dynamic executor method.
 	 */
 	public static byte[] modify(ClassLoader classloader, String name, byte[] bytes) {
-		//		System.out.println("Seen '" + name + "' being defined by " + classloader);
-		//		ClassPrinter.print(bytes, true);
 		ClassLoader parent = classloader.getParent();
 		if (parent != null) {
 			TypeRegistry typeRegistry = TypeRegistry.getTypeRegistryFor(parent);

springloaded/src/main/java/org/springsource/loaded/agent/NonFinalizer.java

@@ -38,8 +38,7 @@ public class NonFinalizer extends ClassVisitor implements Constants {
 	 * just before each constructor returns. The target of the call should be a collecting method that will likely do something with
 	 * the instances later on class reload.
 	 * 
-	 * @param owner
-	 * @param name
+	 * @param fieldname the name of the field to be made non final
 	 */
 	public NonFinalizer(String fieldname) {
 		super(ASM5,new ClassWriter(0)); // TODO review 0 here

springloaded/src/main/java/org/springsource/loaded/agent/SpringLoadedAgent.java

@@ -23,7 +23,7 @@ import java.lang.instrument.Instrumentation;
  * it is 'plugged in' to the JVM when '-javaagent:springloaded.jar' is used.
  * 
  * @author Andy Clement
- * @sinc 0.5.0
+ * @since 0.5.0
  */
 public class SpringLoadedAgent {
 

springloaded/src/main/java/org/springsource/loaded/ri/ReflectiveInterceptor.java

@@ -756,8 +756,8 @@ public class ReflectiveInterceptor {
 	/**
 	 * Retrieve modifiers for a Java class, which might or might not be reloadable or reloaded.
 	 * 
-	 * @param clazz
-	 * @return
+	 * @param clazz the class for which to discover modifiers
+	 * @return the modifiers
 	 */
 	public static int jlClassGetModifiers(Class<?> clazz) {
 		//		ReloadableType rtype = getReloadableTypeIfHasBeenReloaded(clazz);
@@ -844,8 +844,8 @@ public class ReflectiveInterceptor {
 	/**
 	 * Access and return the ReloadableType field on a specified class.
 	 * 
-	 * @param clazz
-	 * @return
+	 * @param clazz the class for which to discover the reloadable type
+	 * @return the reloadable type for the class, or null if not reloadable
 	 */
 	public static ReloadableType getRType(Class<?> clazz) {
 		//		ReloadableType rtype = null;