Fix misplaced or incorrect javadoc tags

43 files changed, 92 insertions, 89 deletions

diff --git a/ajbrowser/src/main/java/org/aspectj/tools/ajbrowser/ui/EditorManager.java b/ajbrowser/src/main/java/org/aspectj/tools/ajbrowser/ui/EditorManager.java
index 249992dd7..f58a5c81d 100644
--- a/ajbrowser/src/main/java/org/aspectj/tools/ajbrowser/ui/EditorManager.java
+++ b/ajbrowser/src/main/java/org/aspectj/tools/ajbrowser/ui/EditorManager.java
@@ -32,7 +32,7 @@ import org.aspectj.tools.ajbrowser.core.BrowserErrorHandler;
 /**
  * Responsible for controlling the editor.
  * 
- * @todo remove coupling to <CODE>BasicEditor</CODE>
+ * <p><b>TODO:</b> remove coupling to <CODE>BasicEditor</CODE></p>
  * @author Mik Kersten
  */
 public class EditorManager {
@@ -117,7 +117,7 @@ public class EditorManager {
 	}
 
 	/**
-	 * @todo remove "instanceof AjdeManager" hack
+	 * <b>TODO</b>: remove "instanceof AjdeManager" hack
 	 */
 	public void showSourceLine(String filePath, int lineNumber, boolean highlight) {
 		if (editors.size() > 1) {
diff --git a/ajde/src/main/java/org/aspectj/ajde/Ajde.java b/ajde/src/main/java/org/aspectj/ajde/Ajde.java
index 14995d75d..1446e8278 100644
--- a/ajde/src/main/java/org/aspectj/ajde/Ajde.java
+++ b/ajde/src/main/java/org/aspectj/ajde/Ajde.java
@@ -160,7 +160,6 @@ public class Ajde {
 	 * Utility to run the project main class from the project properties in the same VM using a class loader populated with the
 	 * classpath and output path or jar. Errors are logged to the ErrorHandler.
 	 * 
-	 * @param project the ProjectPropertiesAdapter specifying the main class, classpath, and executable arguments.
 	 * @return Thread running with process, or null if unable to start
 	 */
 	public Thread runInSameVM() {
diff --git a/ajde/src/main/java/org/aspectj/ajde/internal/BuildConfigManager.java b/ajde/src/main/java/org/aspectj/ajde/internal/BuildConfigManager.java
index d61cbc6b3..310662335 100644
--- a/ajde/src/main/java/org/aspectj/ajde/internal/BuildConfigManager.java
+++ b/ajde/src/main/java/org/aspectj/ajde/internal/BuildConfigManager.java
@@ -39,7 +39,7 @@ public interface BuildConfigManager {
 	/**
 	 * Sets the currently active build configuration file.
 	 *
-	 * @param	full path to the file
+	 * @param currConfigFilePath	full path to the file
 	 */
 	void setActiveConfigFile(String currConfigFilePath);
 
@@ -56,7 +56,7 @@ public interface BuildConfigManager {
 	/**
 	 * Build a model for the corresponding configuration file.
 	 *
-	 * @param	full path to the file
+	 * @param configFilePath	full path to the file
 	 */
 	BuildConfigModel buildModel(String configFilePath);
 
diff --git a/ajde/src/main/java/org/aspectj/ajde/ui/BuildConfigEditor.java b/ajde/src/main/java/org/aspectj/ajde/ui/BuildConfigEditor.java
index a56fc51b0..8e7d26e58 100644
--- a/ajde/src/main/java/org/aspectj/ajde/ui/BuildConfigEditor.java
+++ b/ajde/src/main/java/org/aspectj/ajde/ui/BuildConfigEditor.java
@@ -22,7 +22,7 @@ import java.io.IOException;
 public interface BuildConfigEditor {
 
 	/**
-	 * @param	the full path to the file resource to be opened
+	 * @param filePath	the full path to the file resource to be opened
 	 */
 	void openFile(String filePath) throws IOException, InvalidResourceException;
 }
diff --git a/ajde/src/main/java/org/aspectj/ajde/ui/internal/TreeStructureViewBuilder.java b/ajde/src/main/java/org/aspectj/ajde/ui/internal/TreeStructureViewBuilder.java
index a8a07ee34..9d885396d 100644
--- a/ajde/src/main/java/org/aspectj/ajde/ui/internal/TreeStructureViewBuilder.java
+++ b/ajde/src/main/java/org/aspectj/ajde/ui/internal/TreeStructureViewBuilder.java
@@ -43,7 +43,7 @@ public class TreeStructureViewBuilder {
 	}
 
 	/**
-	 * @todo	get rid of instanceof tests
+	 * <b>TODO</b>:	get rid of instanceof tests
 	 */
 	public void buildView(StructureView view, IHierarchy model) {
 		//		StructureViewProperties properties = view.getViewProperties();
diff --git a/ajde/src/main/java/org/aspectj/ajde/ui/swing/BuildProgressPanel.java b/ajde/src/main/java/org/aspectj/ajde/ui/swing/BuildProgressPanel.java
index 8b778cd8a..ac8dcf2a0 100644
--- a/ajde/src/main/java/org/aspectj/ajde/ui/swing/BuildProgressPanel.java
+++ b/ajde/src/main/java/org/aspectj/ajde/ui/swing/BuildProgressPanel.java
@@ -45,10 +45,6 @@ public class BuildProgressPanel extends JPanel {
 
     private boolean buildIsCancelled = false;
 	
-	/**
-	 * @param   maxVal          the value to which value to which the progress bar will
-	 *                          count up to (in seconds)
-	 */
 	public BuildProgressPanel() {
 		try {
 			jbInit();
@@ -83,6 +79,10 @@ public class BuildProgressPanel extends JPanel {
 		compile_progressBar.setValue(newVal);
 	}
 
+	/**
+	 * @param   maxVal          the value to which value to which the progress bar will
+	 *                          count up to (in seconds)
+	 */
 	public void setProgressBarMax(int maxVal) {
 		compile_progressBar.setMaximum(maxVal);
 	}
diff --git a/ajde/testdata/examples/spacewar/spacewar/Game.java b/ajde/testdata/examples/spacewar/spacewar/Game.java
index da67d7bc3..54b1bf2ac 100644
--- a/ajde/testdata/examples/spacewar/spacewar/Game.java
+++ b/ajde/testdata/examples/spacewar/spacewar/Game.java
@@ -68,7 +68,7 @@ public class Game extends Thread {
      * thread.  You can instantiate multiple games at once.  For the time being
      * the only way to end the game is to exit from the Java VM.
      *
-     * @param isDemo Controls whether the game runs in demo mode or not.  True
+     * @param mode Controls whether the game runs in demo mode or not.  True
      *   means it is a demo, false means it runs in normal 2 player mode.
      */
     public Game(String mode) {
diff --git a/ajdoc/testdata/spacewar/spacewar/Game.java b/ajdoc/testdata/spacewar/spacewar/Game.java
index da67d7bc3..54b1bf2ac 100644
--- a/ajdoc/testdata/spacewar/spacewar/Game.java
+++ b/ajdoc/testdata/spacewar/spacewar/Game.java
@@ -68,7 +68,7 @@ public class Game extends Thread {
      * thread.  You can instantiate multiple games at once.  For the time being
      * the only way to end the game is to exit from the Java VM.
      *
-     * @param isDemo Controls whether the game runs in demo mode or not.  True
+     * @param mode Controls whether the game runs in demo mode or not.  True
      *   means it is a demo, false means it runs in normal 2 player mode.
      */
     public Game(String mode) {
diff --git a/asm/src/main/java/org/aspectj/asm/IHierarchy.java b/asm/src/main/java/org/aspectj/asm/IHierarchy.java
index f411b2507..cadbb6549 100644
--- a/asm/src/main/java/org/aspectj/asm/IHierarchy.java
+++ b/asm/src/main/java/org/aspectj/asm/IHierarchy.java
@@ -75,12 +75,12 @@ public interface IHierarchy extends Serializable {
 
 	/**
 	 * @param packageName if null default package is searched
-	 * @param className can't be null
+	 * @param typeName can't be null
 	 */
 	IProgramElement findElementForType(String packageName, String typeName);
 
 	/**
-	 * @param sourceFilePath modified to '/' delimited path for consistency
+	 * @param sourceFile modified to '/' delimited path for consistency
 	 * @return a new structure node for the file if it was not found in the model
 	 */
 	IProgramElement findElementForSourceFile(String sourceFile);
diff --git a/asm/src/main/java/org/aspectj/asm/IProgramElement.java b/asm/src/main/java/org/aspectj/asm/IProgramElement.java
index 80e0a59da..95c796b65 100644
--- a/asm/src/main/java/org/aspectj/asm/IProgramElement.java
+++ b/asm/src/main/java/org/aspectj/asm/IProgramElement.java
@@ -95,7 +95,7 @@ public interface IProgramElement extends Serializable {
 	String getPackageName();
 
 	/**
-	 * @param method
+	 * @param returnType
 	 *            return types or field types
 	 */
 	void setCorrespondingType(String returnType);
diff --git a/asm/src/main/java/org/aspectj/asm/internal/AspectJElementHierarchy.java b/asm/src/main/java/org/aspectj/asm/internal/AspectJElementHierarchy.java
index c524c554a..4efe0401e 100644
--- a/asm/src/main/java/org/aspectj/asm/internal/AspectJElementHierarchy.java
+++ b/asm/src/main/java/org/aspectj/asm/internal/AspectJElementHierarchy.java
@@ -321,7 +321,7 @@ public class AspectJElementHierarchy implements IHierarchy {
 	}
 
 	/**
-	 * @param sourceFilePath modified to '/' delimited path for consistency
+	 * @param sourceFile modified to '/' delimited path for consistency
 	 * @return a new structure node for the file if it was not found in the model
 	 */
 	public IProgramElement findElementForSourceFile(String sourceFile) {
diff --git a/bridge/src/main/java/org/aspectj/bridge/IMessage.java b/bridge/src/main/java/org/aspectj/bridge/IMessage.java
index 694da8af0..256db87ac 100644
--- a/bridge/src/main/java/org/aspectj/bridge/IMessage.java
+++ b/bridge/src/main/java/org/aspectj/bridge/IMessage.java
@@ -146,5 +146,18 @@ public interface IMessage {
 	 * being based on a subtype of a defining type.
 	 * @see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=41952">AspectJ bug 41952</a>
 	 */
+	/**
+	 * Return a List of <code>ISourceLocation</code> instances that indicate additional source locations relevent to this message as
+	 *         specified by the message creator. The list should not include the primary source location associated with the message
+	 *         which can be obtained from <code>getSourceLocation()<code>.
+	 * <p>
+	 * An example of using extra locations would be in a warning message that
+	 * flags all shadow locations that will go unmatched due to a pointcut definition
+	 * being based on a subtype of a defining type.
+	 * </p>
+	 *
+	 * @return a list of additional source locations
+	 * @see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=41952">AspectJ bug 41952</a>
+	 */
 	List<ISourceLocation> getExtraSourceLocations();
 }
diff --git a/bridge/src/main/java/org/aspectj/bridge/MessageUtil.java b/bridge/src/main/java/org/aspectj/bridge/MessageUtil.java
index 0385ba696..3d9d8c69d 100644
--- a/bridge/src/main/java/org/aspectj/bridge/MessageUtil.java
+++ b/bridge/src/main/java/org/aspectj/bridge/MessageUtil.java
@@ -260,7 +260,7 @@ public class MessageUtil {
 	/**
 	 * Print all message to the print stream, starting each on a new line, with a prefix.
 	 *
-	 * @param messageHolder
+	 * @param holder
 	 * @param out
 	 * @see #print(PrintStream, String, IMessageHolder, IMessageRenderer, IMessageHandler)
 	 */
@@ -271,7 +271,7 @@ public class MessageUtil {
 	/**
 	 * Print all message to the print stream, starting each on a new line, with a prefix and using a renderer.
 	 *
-	 * @param messageHolder
+	 * @param holder
 	 * @param out
 	 * @param renderer IMessageRender to render result - use MESSAGE_LINE if null
 	 * @see #print(PrintStream, String, IMessageHolder, IMessageRenderer, IMessageHandler)
@@ -292,7 +292,8 @@ public class MessageUtil {
 	 * are free to render multi-line output.
 	 *
 	 * @param out the PrintStream sink - return silently if null
-	 * @param messageHolder the IMessageHolder with the messages to print
+	 * @param holder the IMessageHolder with the messages to print
+	 * @param prefix the prefix for each line
 	 * @param renderer IMessageRender to render result - use MESSAGE_ALL if null
 	 * @param selector IMessageHandler to select messages to render - if null, do all non-null
 	 */
@@ -1038,8 +1039,8 @@ public class MessageUtil {
 	/**
 	 * Handle all messages in the second handler using the first
 	 *
-	 * @param handler the IMessageHandler sink for all messages in source
-	 * @param holder the IMessageHolder source for all messages to handle
+	 * @param sink the IMessageHandler sink for all messages in source
+	 * @param source the IMessageHolder source for all messages to handle
 	 * @param fastFail if true, stop on first failure
 	 * @return false if any sink.handleMessage(..) failed
 	 */
@@ -1050,8 +1051,8 @@ public class MessageUtil {
 	/**
 	 * Handle messages in the second handler using the first
 	 *
-	 * @param handler the IMessageHandler sink for all messages in source
-	 * @param holder the IMessageHolder source for all messages to handle
+	 * @param sink the IMessageHandler sink for all messages in source
+	 * @param source the IMessageHolder source for all messages to handle
 	 * @param kind the IMessage.Kind to select, if not null
 	 * @param orGreater if true, also accept greater kinds
 	 * @param fastFail if true, stop on first failure
@@ -1068,8 +1069,8 @@ public class MessageUtil {
 	 * Handle messages in the second handler using the first if they are NOT of this kind (optionally, or greater). If you pass null
 	 * as the kind, then all messages are ignored and this returns true.
 	 *
-	 * @param handler the IMessageHandler sink for all messages in source
-	 * @param holder the IMessageHolder source for all messages to handle
+	 * @param sink the IMessageHandler sink for all messages in source
+	 * @param source the IMessageHolder source for all messages to handle
 	 * @param kind the IMessage.Kind to reject, if not null
 	 * @param orGreater if true, also reject greater kinds
 	 * @param fastFail if true, stop on first failure
@@ -1089,7 +1090,7 @@ public class MessageUtil {
 	/**
 	 * Handle messages in the sink.
 	 *
-	 * @param handler the IMessageHandler sink for all messages in source
+	 * @param sink the IMessageHandler sink for all messages in source
 	 * @param sources the IMessage[] messages to handle
 	 * @param fastFail if true, stop on first failure
 	 * @return false if any sink.handleMessage(..) failed
diff --git a/docs/dist/doc/examples/spacewar/Game.java b/docs/dist/doc/examples/spacewar/Game.java
index da67d7bc3..54b1bf2ac 100644
--- a/docs/dist/doc/examples/spacewar/Game.java
+++ b/docs/dist/doc/examples/spacewar/Game.java
@@ -68,7 +68,7 @@ public class Game extends Thread {
      * thread.  You can instantiate multiple games at once.  For the time being
      * the only way to end the game is to exit from the Java VM.
      *
-     * @param isDemo Controls whether the game runs in demo mode or not.  True
+     * @param mode Controls whether the game runs in demo mode or not.  True
      *   means it is a demo, false means it runs in normal 2 player mode.
      */
     public Game(String mode) {
diff --git a/docs/teaching/demos/spacewar/src/spacewar/Game.java b/docs/teaching/demos/spacewar/src/spacewar/Game.java
index da67d7bc3..54b1bf2ac 100644
--- a/docs/teaching/demos/spacewar/src/spacewar/Game.java
+++ b/docs/teaching/demos/spacewar/src/spacewar/Game.java
@@ -68,7 +68,7 @@ public class Game extends Thread {
      * thread.  You can instantiate multiple games at once.  For the time being
      * the only way to end the game is to exit from the Java VM.
      *
-     * @param isDemo Controls whether the game runs in demo mode or not.  True
+     * @param mode Controls whether the game runs in demo mode or not.  True
      *   means it is a demo, false means it runs in normal 2 player mode.
      */
     public Game(String mode) {
diff --git a/loadtime/src/main/java/org/aspectj/weaver/loadtime/DefaultWeavingContext.java b/loadtime/src/main/java/org/aspectj/weaver/loadtime/DefaultWeavingContext.java
index 8e8d9df77..5117a95b2 100644
--- a/loadtime/src/main/java/org/aspectj/weaver/loadtime/DefaultWeavingContext.java
+++ b/loadtime/src/main/java/org/aspectj/weaver/loadtime/DefaultWeavingContext.java
@@ -119,7 +119,7 @@ public class DefaultWeavingContext implements IWeavingContext {
 	/**
 	 * Simply call weaving adaptor back to parse aop.xml
 	 * 
-	 * @param weaver
+	 * @param adaptor
 	 * @param loader
 	 */
 	public List<Definition> getDefinitions(final ClassLoader loader, final WeavingAdaptor adaptor) {
diff --git a/org.aspectj.ajdt.core/src/main/java/org/aspectj/ajdt/internal/compiler/AjCompilerAdapter.java b/org.aspectj.ajdt.core/src/main/java/org/aspectj/ajdt/internal/compiler/AjCompilerAdapter.java
index 664260cb5..dd9d9c0a9 100644
--- a/org.aspectj.ajdt.core/src/main/java/org/aspectj/ajdt/internal/compiler/AjCompilerAdapter.java
+++ b/org.aspectj.ajdt.core/src/main/java/org/aspectj/ajdt/internal/compiler/AjCompilerAdapter.java
@@ -76,8 +76,8 @@ public class AjCompilerAdapter extends AbstractCompilerAdapter {
 	 * @param weaver the weaver
 	 * @param intRequestor recipient of interim compilation results from compiler (pre-weave)
 	 * @param outputFileNameProvider implementor of a strategy providing output file names for results
-	 * @param binarySourceEntries binary source that we didn't compile, but that we need to weave
-	 * @param resultSetForFullWeave if we are doing an incremental build, and the weaver determines that we need to weave the world,
+	 * @param binarySourceProvider binary source that we didn't compile, but that we need to weave
+	 * @param incrementalCompilationState if we are doing an incremental build, and the weaver determines that we need to weave the world,
 	 *        this is the set of intermediate results that will be passed to the weaver.
 	 */
 	public AjCompilerAdapter(Compiler compiler, boolean isBatchCompile, BcelWorld world, BcelWeaver weaver,
diff --git a/org.aspectj.ajdt.core/src/main/java/org/aspectj/ajdt/internal/compiler/AjPipeliningCompilerAdapter.java b/org.aspectj.ajdt.core/src/main/java/org/aspectj/ajdt/internal/compiler/AjPipeliningCompilerAdapter.java
index 5bfe243d5..e576ee0d3 100644
--- a/org.aspectj.ajdt.core/src/main/java/org/aspectj/ajdt/internal/compiler/AjPipeliningCompilerAdapter.java
+++ b/org.aspectj.ajdt.core/src/main/java/org/aspectj/ajdt/internal/compiler/AjPipeliningCompilerAdapter.java
@@ -135,8 +135,8 @@ public class AjPipeliningCompilerAdapter extends AbstractCompilerAdapter {
 	 * @param weaver the weaver
 	 * @param intRequestor recipient of interim compilation results from compiler (pre-weave)
 	 * @param outputFileNameProvider implementor of a strategy providing output file names for results
-	 * @param binarySourceEntries binary source that we didn't compile, but that we need to weave
-	 * @param resultSetForFullWeave if we are doing an incremental build, and the weaver determines that we need to weave the world,
+	 * @param binarySourceProvider binary source that we didn't compile, but that we need to weave
+	 * @param incrementalCompilationState if we are doing an incremental build, and the weaver determines that we need to weave the world,
 	 *        this is the set of intermediate results that will be passed to the weaver.
 	 */
 	public AjPipeliningCompilerAdapter(Compiler compiler, boolean isBatchCompile, BcelWorld world, BcelWeaver weaver,
diff --git a/org.aspectj.ajdt.core/src/main/java/org/aspectj/tools/ajc/Main.java b/org.aspectj.ajdt.core/src/main/java/org/aspectj/tools/ajc/Main.java
index e372b5527..7cbc3e341 100644
--- a/org.aspectj.ajdt.core/src/main/java/org/aspectj/tools/ajc/Main.java
+++ b/org.aspectj.ajdt.core/src/main/java/org/aspectj/tools/ajc/Main.java
@@ -87,15 +87,15 @@ public class Main {
 	/**
 	 * Convenience method to run ajc and collect String lists of messages. This can be reflectively invoked with the List collecting
 	 * parameters supplied by a parent class loader. The String messages take the same form as command-line messages.
+	 * This method does not catch unchecked exceptions thrown by the compiler.
 	 * 
 	 * @param args the String[] args to pass to the compiler
 	 * @param useSystemExit if true and errors, return System.exit(errs)
 	 * @param fails the List sink, if any, for String failure (or worse) messages
 	 * @param errors the List sink, if any, for String error messages
 	 * @param warnings the List sink, if any, for String warning messages
-	 * @param info the List sink, if any, for String info messages
+	 * @param infos the List sink, if any, for String info messages
 	 * @return number of messages reported with level ERROR or above
-	 * @throws any unchecked exceptions the compiler does
 	 */
 	public static int bareMain(String[] args, boolean useSystemExit, List fails, List errors, List warnings, List infos) {
 		Main main = new Main();
@@ -453,7 +453,6 @@ public class Main {
 	 * Call System.exit(int) with values derived from the number of failures/aborts or errors in messages.
 	 * 
 	 * @param messages the IMessageHolder to interrogate.
-	 * @param messages
 	 */
 	protected void systemExit(IMessageHolder messages) {
 		int num = lastFails; // messages.numMessages(IMessage.FAIL, true);
@@ -725,7 +724,7 @@ public class Main {
 		}
 
 		/**
-		 * @param argList read and strip incremental args from this
+		 * @param args read and strip incremental args from this
 		 * @param sink IMessageHandler for error messages
 		 * @return String[] remainder of args
 		 */
diff --git a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/AjAttribute.java b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/AjAttribute.java
index e76c88f88..fd65867ae 100644
--- a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/AjAttribute.java
+++ b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/AjAttribute.java
@@ -68,7 +68,7 @@ public abstract class AjAttribute {
 	/**
 	 * Writes the full attribute, i.e. name_index, length, and contents
 	 * 
-	 * @param constantPool
+	 * @param dataCompressor
 	 */
 	public byte[] getAllBytes(short nameIndex, ConstantPoolWriter dataCompressor) {
 		try {
@@ -525,7 +525,7 @@ public abstract class AjAttribute {
 		private UnresolvedType[] declaredExceptions;
 
 		/**
-		 * @param lexicalPosition must be greater than the lexicalPosition of any advice declared before this one in an aspect,
+		 * @param start must be greater than the start of any advice declared before this one in an aspect,
 		 *        otherwise, it can be any value.
 		 */
 		public AdviceAttribute(AdviceKind kind, Pointcut pointcut, int extraArgumentFlags, int start, int end,
diff --git a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/IWeavingSupport.java b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/IWeavingSupport.java
index 5fe48a520..70bb1d67a 100644
--- a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/IWeavingSupport.java
+++ b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/IWeavingSupport.java
@@ -17,7 +17,7 @@ import org.aspectj.weaver.patterns.Pointcut;
 
 /**
  * Encapsulates operations that a world will need to support if it is actually going to modify bytecode rather than just match
- * against it. {@see BcelWeavingSupport}
+ * against it. @see BcelWeavingSupport
  *
  * @author Andy Clement
  */
@@ -31,7 +31,7 @@ public interface IWeavingSupport {
 	ConcreteTypeMunger makeCflowCounterFieldAdder(ResolvedMember cflowField);
 
 	/**
-	 * Register a munger for perclause @AJ aspect so that we add aspectOf(..) to them as needed
+	 * Register a munger for perclause {@literal @}AJ aspect so that we add aspectOf(..) to them as needed
 	 *
 	 * @see org.aspectj.weaver.bcel.BcelWorld#makePerClauseAspect(ResolvedType, org.aspectj.weaver.patterns.PerClause.Kind)
 	 */
diff --git a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/ResolvedType.java b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/ResolvedType.java
index 59f767148..736564867 100644
--- a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/ResolvedType.java
+++ b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/ResolvedType.java
@@ -313,15 +313,20 @@ public abstract class ResolvedType extends UnresolvedType implements AnnotatedEl
 	/**
 	 * Return an iterator over the types in this types hierarchy - starting with this type first, then all superclasses up to Object
 	 * and then all interfaces (starting with those 'nearest' this type).
-	 * 
-	 * @param wantGenerics true if the caller wants full generic information
-	 * @param wantDeclaredParents true if the caller even wants those parents introduced via declare parents
 	 * @return an iterator over all types in the hierarchy of this type
 	 */
 	public Iterator<ResolvedType> getHierarchy() {
 		return getHierarchy(false, false);
 	}
 
+	/**
+	 * Return an iterator over the types in this types hierarchy - starting with this type first, then all superclasses up to Object
+	 * and then all interfaces (starting with those 'nearest' this type).
+	 *
+	 * @param wantGenerics true if the caller wants full generic information
+	 * @param wantDeclaredParents true if the caller even wants those parents introduced via declare parents
+	 * @return an iterator over all types in the hierarchy of this type
+	 */
 	public Iterator<ResolvedType> getHierarchy(final boolean wantGenerics, final boolean wantDeclaredParents) {
 
 		final Iterators.Getter<ResolvedType, ResolvedType> interfaceGetter = new Iterators.Getter<ResolvedType, ResolvedType>() {
@@ -2622,7 +2627,6 @@ public abstract class ResolvedType extends UnresolvedType implements AnnotatedEl
 	 * assignable to a variable of type X without loss of precision.
 	 * 
 	 * @param other the other type
-	 * @param world the {@link World} in which the possible assignment should be checked.
 	 * @return true iff variables of this type could be assigned values of other with possible conversion
 	 */
 	public final boolean isConvertableFrom(ResolvedType other) {
@@ -2660,7 +2664,6 @@ public abstract class ResolvedType extends UnresolvedType implements AnnotatedEl
 	 * assignment conversion as per JLS 2ed 5.2. For object types, this means supertypeOrEqual(THIS, OTHER).
 	 * 
 	 * @param other the other type
-	 * @param world the {@link World} in which the possible assignment should be checked.
 	 * @return true iff variables of this type could be assigned values of other without casting
 	 * @throws NullPointerException if other is null
 	 */
@@ -2683,7 +2686,6 @@ public abstract class ResolvedType extends UnresolvedType implements AnnotatedEl
 	 * </blockquote>
 	 * 
 	 * @param other the other type
-	 * @param world the {@link World} in which the possible coersion should be checked.
 	 * @return true iff values of other could possibly be cast to this type.
 	 * @throws NullPointerException if other is null.
 	 */
diff --git a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/TypeFactory.java b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/TypeFactory.java
index 74afc6cae..c747ffe53 100644
--- a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/TypeFactory.java
+++ b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/TypeFactory.java
@@ -20,7 +20,7 @@ public class TypeFactory {
 	/**
 	 * Create a parameterized version of a generic type.
 	 * 
-	 * @param aGenericType
+	 * @param aBaseType
 	 * @param someTypeParameters note, in the case of an inner type of a parameterized type, this parameter may legitimately be null
 	 * @param inAWorld
 	 * @return
diff --git a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/UnresolvedType.java b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/UnresolvedType.java
index 19f1ca5ce..237cb05f8 100644
--- a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/UnresolvedType.java
+++ b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/UnresolvedType.java
@@ -422,7 +422,7 @@ public class UnresolvedType implements Traceable, TypeVariableDeclaringElement {
 	/**
 	 * Constructs a UnresolvedType for each JVM bytecode type signature in an incoming array.
 	 * 
-	 * @param names an array of JVM bytecode type signatures
+	 * @param sigs an array of JVM bytecode type signatures
 	 * @return an array of UnresolvedType objects.
 	 * @see #forSignature(String)
 	 */
diff --git a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/AnyTypePattern.java b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/AnyTypePattern.java
index db9ba5130..b72a9561d 100644
--- a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/AnyTypePattern.java
+++ b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/AnyTypePattern.java
@@ -23,9 +23,7 @@ import org.aspectj.weaver.World;
 public class AnyTypePattern extends TypePattern {
 
 	/**
-	 * Constructor for EllipsisTypePattern.
-	 * 
-	 * @param includeSubtypes
+	 * Constructor for AnyTypePattern.
 	 */
 	public AnyTypePattern() {
 		super(false, false, new TypePatternList());
diff --git a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/EllipsisTypePattern.java b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/EllipsisTypePattern.java
index 2abc51327..ab3541799 100644
--- a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/EllipsisTypePattern.java
+++ b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/EllipsisTypePattern.java
@@ -23,8 +23,6 @@ public class EllipsisTypePattern extends TypePattern {
 
 	/**
 	 * Constructor for EllipsisTypePattern.
-	 * 
-	 * @param includeSubtypes
 	 */
 	public EllipsisTypePattern() {
 		super(false, false, new TypePatternList());
diff --git a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/PatternParser.java b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/PatternParser.java
index f7ffafdf4..7bb806b39 100644
--- a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/PatternParser.java
+++ b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/PatternParser.java
@@ -1687,7 +1687,6 @@ public class PatternParser {
 	 * Parse type variable declarations for a generic method or at the start of a signature pointcut to identify type variable names
 	 * in a generic type.
 	 * 
-	 * @param includeParameterizedTypes
 	 * @return
 	 */
 	public TypeVariablePatternList maybeParseTypeVariableList() {
diff --git a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/PointcutEvaluationExpenseComparator.java b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/PointcutEvaluationExpenseComparator.java
index 5f3a3291f..60f3989ea 100644
--- a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/PointcutEvaluationExpenseComparator.java
+++ b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/patterns/PointcutEvaluationExpenseComparator.java
@@ -41,11 +41,11 @@ public class PointcutEvaluationExpenseComparator implements Comparator<Pointcut>
 	 * 
 	 * within
 	 * 
-	 * @within staticinitialization [make sure this has a fast match method] adviceexecution handler get, set withincode
-	 * @withincode execution, initialization, preinitialization call
-	 * @annotation this, target
-	 * @this, @target args
-	 * @args cflow, cflowbelow if
+	 * {@literal @}within staticinitialization [make sure this has a fast match method] adviceexecution handler get, set withincode
+	 * {@literal @}withincode execution, initialization, preinitialization call
+	 * {@literal @}annotation this, target
+	 * {@literal @}this, {@literal @}target args
+	 * {@literal @}args cflow, cflowbelow if
 	 */
 	public int compare(Pointcut p1, Pointcut p2) {
 		// important property for a well-defined comparator
diff --git a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/tools/AbstractTrace.java b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/tools/AbstractTrace.java
index 252a164fe..fe2f86f54 100644
--- a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/tools/AbstractTrace.java
+++ b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/tools/AbstractTrace.java
@@ -189,7 +189,6 @@ public abstract class AbstractTrace implements Trace {
 	/**
 	 * Format arguments into a comma separated list
 	 *
-	 * @param names array of argument names
 	 * @param args array of arguments
 	 * @return the formated list
 	 */
diff --git a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/tools/PointcutExpression.java b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/tools/PointcutExpression.java
index 6b598a50c..a2016980d 100644
--- a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/tools/PointcutExpression.java
+++ b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/tools/PointcutExpression.java
@@ -109,7 +109,6 @@ public interface PointcutExpression {
 	 * static initialization of the type).
 	 * @param aMethod the method being called
 	 * @param callerType the declared type of the caller
-	 * @param receiverType the declared type of the recipient of the call
 	 * @return a ShadowMatch indicating whether the pointcut always, sometimes, or never
 	 * matches join points representing a call to this method during the execution of the given member.
 	 */
diff --git a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/tools/StandardPointcutExpression.java b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/tools/StandardPointcutExpression.java
index 63d908bd2..6ea1eefd1 100644
--- a/org.aspectj.matcher/src/main/java/org/aspectj/weaver/tools/StandardPointcutExpression.java
+++ b/org.aspectj.matcher/src/main/java/org/aspectj/weaver/tools/StandardPointcutExpression.java
@@ -60,7 +60,7 @@ public interface StandardPointcutExpression {
 	/**
 	 * Determine whether or not this pointcut matches the static initialization of the given class.
 	 * 
-	 * @param aClass the class being statically initialized
+	 * @param aType the class being statically initialized
 	 * @return a ShadowMatch indicating whether the pointcut always, sometimes, or never matchs join points representing the static
 	 *         initialization of the given type
 	 */
diff --git a/taskdefs/src/main/java/org/aspectj/tools/ant/taskdefs/Ajc2.java b/taskdefs/src/main/java/org/aspectj/tools/ant/taskdefs/Ajc2.java
index 68824ca80..624410298 100644
--- a/taskdefs/src/main/java/org/aspectj/tools/ant/taskdefs/Ajc2.java
+++ b/taskdefs/src/main/java/org/aspectj/tools/ant/taskdefs/Ajc2.java
@@ -175,9 +175,9 @@ public class Ajc2 extends Javac {
     }
 
     /**
-     * Returns if the <code>-preprocess</code> flag is turned on.
+     * Set the <code>-preprocess</code> flag.
      *
-     * @return <code>true</code> if the <code>-preprocess</code> flag is on.
+     * @param preprocess <code>true</code> turns on the <code>-preprocess</code> flag.
      * @see    Ajc2#preprocess
      */
     public void setPreprocess(boolean preprocess) {
diff --git a/taskdefs/src/main/java/org/aspectj/tools/ant/taskdefs/AjcTask.java b/taskdefs/src/main/java/org/aspectj/tools/ant/taskdefs/AjcTask.java
index 34db3e9c5..f2c17081b 100644
--- a/taskdefs/src/main/java/org/aspectj/tools/ant/taskdefs/AjcTask.java
+++ b/taskdefs/src/main/java/org/aspectj/tools/ant/taskdefs/AjcTask.java
@@ -114,8 +114,6 @@ public class AjcTask extends MatchingTask {
 	 * </pre>
 	 *
 	 * @param javac the Javac command to implement (not null)
-	 * @param ajc the AjcTask to adapt (not null)
-	 * @param destDir the File class destination directory (may be null)
 	 * @return null if no error, or String error otherwise
 	 */
 	public String setupAjc(Javac javac) {
@@ -1252,7 +1250,7 @@ public class AjcTask extends MatchingTask {
 	}
 
 	/**
-	 * @throw BuildException if options conflict
+	 * @throws BuildException if options conflict
 	 */
 	protected void verifyOptions() {
 		StringBuffer sb = new StringBuffer();
@@ -1509,7 +1507,6 @@ public class AjcTask extends MatchingTask {
 	}
 
 	// ------------------------------ setup and reporting
-	/** @return null if path null or empty, String rendition otherwise */
 	protected static void addFlaggedPath(String flag, Path path, List<String> list) {
 		if (!LangUtil.isEmpty(flag) && ((null != path) && (0 < path.size()))) {
 			list.add(flag);
diff --git a/tests/ajde/examples/spacewar/spacewar/Game.java b/tests/ajde/examples/spacewar/spacewar/Game.java
index 6b7cf6da9..b7d9d3a50 100644
--- a/tests/ajde/examples/spacewar/spacewar/Game.java
+++ b/tests/ajde/examples/spacewar/spacewar/Game.java
@@ -44,7 +44,7 @@ public class Game extends Thread {
      * thread.  You can instantiate multiple games at once.  For the time being
      * the only way to end the game is to exit from the Java VM.
      *
-     * @param isDemo Controls whether the game runs in demo mode or not.  True
+     * @param mode Controls whether the game runs in demo mode or not.  True
      *   means it is a demo, false means it runs in normal 2 player mode.
      */
     public Game(String mode) {
diff --git a/tests/multiIncremental/SpaceWar/base/src/spacewar/Game.java b/tests/multiIncremental/SpaceWar/base/src/spacewar/Game.java
index da67d7bc3..54b1bf2ac 100644
--- a/tests/multiIncremental/SpaceWar/base/src/spacewar/Game.java
+++ b/tests/multiIncremental/SpaceWar/base/src/spacewar/Game.java
@@ -68,7 +68,7 @@ public class Game extends Thread {
      * thread.  You can instantiate multiple games at once.  For the time being
      * the only way to end the game is to exit from the Java VM.
      *
-     * @param isDemo Controls whether the game runs in demo mode or not.  True
+     * @param mode Controls whether the game runs in demo mode or not.  True
      *   means it is a demo, false means it runs in normal 2 player mode.
      */
     public Game(String mode) {
diff --git a/util/src/main/java/org/aspectj/util/FileUtil.java b/util/src/main/java/org/aspectj/util/FileUtil.java
index 588a46c43..34b2cc17f 100644
--- a/util/src/main/java/org/aspectj/util/FileUtil.java
+++ b/util/src/main/java/org/aspectj/util/FileUtil.java
@@ -324,7 +324,7 @@ public class FileUtil {
 	/**
 	 * Flatten File[] to String.
 	 *
-	 * @param files the File[] of paths to flatten - null ignored
+	 * @param paths the String[] of paths to flatten - null ignored
 	 * @param infix the String infix to use - null treated as File.pathSeparator
 	 */
 	public static String flatten(String[] paths, String infix) {
@@ -1288,9 +1288,9 @@ public class FileUtil {
 	 * result.
 	 *
 	 * @param sought the String text to seek in the file
-	 * @param sources the List of String paths to the source files
+	 * @param sourcePath the String of paths to the source files
 	 * @param listAll if false, only list first match in file
-	 * @param List sink the List for String entries of the form {sourcePath}:line:column
+	 * @param sink the List of String entries of the form {sourcePath}:line:column
 	 * @return String error if any, or add String entries to sink
 	 */
 	public static String lineSeek(String sought, String sourcePath, boolean listAll, List<String> sink) {
diff --git a/util/src/main/java/org/aspectj/util/PartialOrder.java b/util/src/main/java/org/aspectj/util/PartialOrder.java
index ec3ddae28..936bf79ed 100644
--- a/util/src/main/java/org/aspectj/util/PartialOrder.java
+++ b/util/src/main/java/org/aspectj/util/PartialOrder.java
@@ -31,14 +31,14 @@ public class PartialOrder {
 	 */
 	public interface PartialComparable {
 		/**
-		 * @returns <ul>
-		 *          <li>+1 if this is greater than other</li>
-		 *          <li>-1 if this is less than other</li>
-		 *          <li>0 if this is not comparable to other</li>
-		 *          </ul>
+		 * @return <ul>
+		 *         <li>+1 if this is greater than other</li>
+		 *         <li>-1 if this is less than other</li>
+		 *         <li>0 if this is not comparable to other</li>
+		 *         </ul>
 		 *
-		 *          <b> Note: returning 0 from this method doesn't mean the same thing as returning 0 from
-		 *          java.util.Comparable.compareTo()</b>
+		 *         <b> Note: returning 0 from this method doesn't mean the same thing as returning 0 from
+		 *         java.util.Comparable.compareTo()</b>
 		 */
 		int compareTo(Object other);
 
@@ -110,7 +110,7 @@ public class PartialOrder {
 	/**
 	 * @param objects must all implement PartialComparable
 	 *
-	 * @returns the same members as objects, but sorted according to their partial order. returns null if the objects are cyclical
+	 * @return the same members as objects, but sorted according to their partial order. returns null if the objects are cyclical
 	 *
 	 */
 	public static <T extends PartialComparable> List<T> sort(List<T> objects) {
diff --git a/weaver/src/main/java/org/aspectj/weaver/bcel/AnnotationAccessVar.java b/weaver/src/main/java/org/aspectj/weaver/bcel/AnnotationAccessVar.java
index a6ed94b79..f84d5e05e 100644
--- a/weaver/src/main/java/org/aspectj/weaver/bcel/AnnotationAccessVar.java
+++ b/weaver/src/main/java/org/aspectj/weaver/bcel/AnnotationAccessVar.java
@@ -262,7 +262,7 @@ public class AnnotationAccessVar extends BcelVar {
 	 * Return an object that can access a particular value of this annotation.
 	 * 
 	 * @param valueType The type from the annotation that is of interest
-	 * @param the formal name expressed in the pointcut, can be used to disambiguate
+	 * @param formalName the formal name expressed in the pointcut, can be used to disambiguate
 	 * @return a variable that represents access to that annotation value
 	 */
 	@Override
diff --git a/weaver/src/main/java/org/aspectj/weaver/bcel/AtAjAttributes.java b/weaver/src/main/java/org/aspectj/weaver/bcel/AtAjAttributes.java
index 7ad6b6f13..ea907f749 100644
--- a/weaver/src/main/java/org/aspectj/weaver/bcel/AtAjAttributes.java
+++ b/weaver/src/main/java/org/aspectj/weaver/bcel/AtAjAttributes.java
@@ -854,7 +854,7 @@ public class AtAjAttributes {
 	}
 
 	/**
-	 * Return a nicely formatted method string, for example: int X.foo(java.lang.String)
+	 * @return a nicely formatted method string, for example: int X.foo(java.lang.String)
 	 */
 	public static String getMethodForMessage(AjAttributeMethodStruct methodstructure) {
 		StringBuffer sb = new StringBuffer();
diff --git a/weaver/src/main/java/org/aspectj/weaver/bcel/Utility.java b/weaver/src/main/java/org/aspectj/weaver/bcel/Utility.java
index e1e297ad1..368c6b34c 100644
--- a/weaver/src/main/java/org/aspectj/weaver/bcel/Utility.java
+++ b/weaver/src/main/java/org/aspectj/weaver/bcel/Utility.java
@@ -480,7 +480,7 @@ public class Utility {
 	 * replace an instruction handle with another instruction, in this case, a branch instruction.
 	 * 
 	 * @param ih the instruction handle to replace.
-	 * @param branchInstruction the branch instruction to replace ih with
+	 * @param replacementInstructions the branch instruction to replace ih with
 	 * @param enclosingMethod where to find ih's instruction list.
 	 */
 	public static void replaceInstruction(InstructionHandle ih, InstructionList replacementInstructions,
diff --git a/weaver/src/main/java/org/aspectj/weaver/ltw/LTWWorld.java b/weaver/src/main/java/org/aspectj/weaver/ltw/LTWWorld.java
index e7d6ff63e..077a91943 100644
--- a/weaver/src/main/java/org/aspectj/weaver/ltw/LTWWorld.java
+++ b/weaver/src/main/java/org/aspectj/weaver/ltw/LTWWorld.java
@@ -97,7 +97,7 @@ public class LTWWorld extends BcelWorld implements IReflectionWorld {
 	// }
 
 	/**
-	 * @Override
+	 * Override
 	 */
 	@Override
 	protected ReferenceTypeDelegate resolveDelegate(ReferenceType ty) {
diff --git a/weaver/src/main/java/org/aspectj/weaver/tools/WeavingAdaptor.java b/weaver/src/main/java/org/aspectj/weaver/tools/WeavingAdaptor.java
index 5571ad51f..f191da13b 100644
--- a/weaver/src/main/java/org/aspectj/weaver/tools/WeavingAdaptor.java
+++ b/weaver/src/main/java/org/aspectj/weaver/tools/WeavingAdaptor.java
@@ -644,7 +644,6 @@ public class WeavingAdaptor implements IMessageContext {
 	 * @param name
 	 * @param b
 	 * @param before whether we are dumping before weaving
-	 * @throws Throwable
 	 */
 	protected void dump(String name, byte[] b, boolean before) {
 		String dirName = getDumpDir();
diff --git a/weaver/src/main/java/org/aspectj/weaver/tools/cache/AbstractCacheBacking.java b/weaver/src/main/java/org/aspectj/weaver/tools/cache/AbstractCacheBacking.java
index 649e21d05..1fc3d4e61 100644
--- a/weaver/src/main/java/org/aspectj/weaver/tools/cache/AbstractCacheBacking.java
+++ b/weaver/src/main/java/org/aspectj/weaver/tools/cache/AbstractCacheBacking.java
@@ -31,7 +31,7 @@ public abstract class AbstractCacheBacking implements CacheBacking {
      * Calculates CRC32 on the provided bytes
      * @param bytes The bytes array - ignored if <code>null</code>/empty
      * @return Calculated CRC
-     * @see {@link CRC32}
+     * @see CRC32
      */
     public static final long crc (byte[] bytes) {
         if ((bytes == null) || (bytes.length <= 0)) {