polish javadoc in runtime module

59 files changed, 324 insertions, 467 deletions

diff --git a/runtime/src/main/java/org/aspectj/internal/lang/reflect/AjTypeImpl.java b/runtime/src/main/java/org/aspectj/internal/lang/reflect/AjTypeImpl.java
index 5c04def2c..542aeb182 100644
--- a/runtime/src/main/java/org/aspectj/internal/lang/reflect/AjTypeImpl.java
+++ b/runtime/src/main/java/org/aspectj/internal/lang/reflect/AjTypeImpl.java
@@ -604,9 +604,6 @@ public class AjTypeImpl<T> implements AjType<T> {
 		return this.declaredITDMethods;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getITDMethod(java.lang.String, java.lang.Class, java.lang.Class...)
-	 */
 	public InterTypeMethodDeclaration getITDMethod(String name, AjType<?> target,
 			AjType<?>... parameterTypes) 
 	throws NoSuchMethodException {
@@ -632,9 +629,6 @@ public class AjTypeImpl<T> implements AjType<T> {
 		throw new NoSuchMethodException(name);
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getITDMethods()
-	 */
 	public InterTypeMethodDeclaration[] getITDMethods() {
 		if (this.itdMethods == null) {
 			List<InterTypeMethodDeclaration> itdms = new ArrayList<InterTypeMethodDeclaration>();
@@ -685,9 +679,6 @@ public class AjTypeImpl<T> implements AjType<T> {
 		return;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getDeclaredITDConstructor(java.lang.Class, java.lang.Class...)
-	 */
 	public InterTypeConstructorDeclaration getDeclaredITDConstructor(
 			AjType<?> target, AjType<?>... parameterTypes) throws NoSuchMethodException {
 		InterTypeConstructorDeclaration[] itdcs = getDeclaredITDConstructors();
@@ -711,9 +702,6 @@ public class AjTypeImpl<T> implements AjType<T> {
 		throw new NoSuchMethodException();
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getDeclaredITDConstructors()
-	 */
 	public InterTypeConstructorDeclaration[] getDeclaredITDConstructors() {
 		if (this.declaredITDCons == null) {
 			List<InterTypeConstructorDeclaration> itdcs = new ArrayList<InterTypeConstructorDeclaration>();
@@ -733,9 +721,6 @@ public class AjTypeImpl<T> implements AjType<T> {
 		return this.declaredITDCons;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getITDConstructor(java.lang.Class, java.lang.Class...)
-	 */
 	public InterTypeConstructorDeclaration getITDConstructor(AjType<?> target,
 			AjType<?>... parameterTypes) throws NoSuchMethodException {
 		InterTypeConstructorDeclaration[] itdcs = getITDConstructors();
@@ -759,9 +744,6 @@ public class AjTypeImpl<T> implements AjType<T> {
 		throw new NoSuchMethodException();
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getITDConstructors()
-	 */
 	public InterTypeConstructorDeclaration[] getITDConstructors() {
 		if (this.itdCons == null) {
 			List<InterTypeConstructorDeclaration> itdcs = new ArrayList<InterTypeConstructorDeclaration>();
@@ -781,9 +763,6 @@ public class AjTypeImpl<T> implements AjType<T> {
 		}
 		return this.itdCons;	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getDeclaredITDField(java.lang.String, java.lang.Class)
-	 */
 	public InterTypeFieldDeclaration getDeclaredITDField(String name,
 			AjType<?> target) throws NoSuchFieldException {
 		InterTypeFieldDeclaration[] itdfs = getDeclaredITDFields();
@@ -800,9 +779,6 @@ public class AjTypeImpl<T> implements AjType<T> {
 		throw new NoSuchFieldException(name);
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getDeclaredITDFields()
-	 */
 	public InterTypeFieldDeclaration[] getDeclaredITDFields() {
 		List<InterTypeFieldDeclaration> itdfs = new ArrayList<InterTypeFieldDeclaration>();
 		if (this.declaredITDFields == null) {
@@ -833,9 +809,6 @@ public class AjTypeImpl<T> implements AjType<T> {
 		return this.declaredITDFields;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getITDField(java.lang.String, java.lang.Class)
-	 */
 	public InterTypeFieldDeclaration getITDField(String name, AjType<?> target) 
 	throws NoSuchFieldException {
 		InterTypeFieldDeclaration[] itdfs = getITDFields();
@@ -852,9 +825,6 @@ public class AjTypeImpl<T> implements AjType<T> {
 		throw new NoSuchFieldException(name);
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getITDFields()
-	 */
 	public InterTypeFieldDeclaration[] getITDFields() {
 		List<InterTypeFieldDeclaration> itdfs = new ArrayList<InterTypeFieldDeclaration>();
 		if (this.itdFields == null) {
@@ -886,9 +856,6 @@ public class AjTypeImpl<T> implements AjType<T> {
 		return this.itdFields;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getDeclareErrorOrWarnings()
-	 */
 	public DeclareErrorOrWarning[] getDeclareErrorOrWarnings() {
 		List<DeclareErrorOrWarning> deows = new ArrayList<DeclareErrorOrWarning>();
 		for (Field field : clazz.getDeclaredFields()) {
@@ -926,9 +893,6 @@ public class AjTypeImpl<T> implements AjType<T> {
 		return ret;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getDeclareParents()
-	 */
 	public DeclareParents[] getDeclareParents() {
 		List<DeclareParents> decps = new ArrayList<DeclareParents>();
 		for (Method method : clazz.getDeclaredMethods()) {
@@ -969,9 +933,6 @@ public class AjTypeImpl<T> implements AjType<T> {
         }
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getDeclareSofts()
-	 */
 	public DeclareSoft[] getDeclareSofts() {
 		List<DeclareSoft> decs = new ArrayList<DeclareSoft>();
 		for (Method method : clazz.getDeclaredMethods()) {
@@ -993,9 +954,6 @@ public class AjTypeImpl<T> implements AjType<T> {
 		return ret;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getDeclareAnnotations()
-	 */
 	public DeclareAnnotation[] getDeclareAnnotations() {
 		List<DeclareAnnotation> decAs = new ArrayList<DeclareAnnotation>();
 		for (Method method : clazz.getDeclaredMethods()) {
@@ -1029,9 +987,6 @@ public class AjTypeImpl<T> implements AjType<T> {
 		return ret;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getDeclarePrecedence()
-	 */
 	public DeclarePrecedence[] getDeclarePrecedence() {
 		List<DeclarePrecedence> decps = new ArrayList<DeclarePrecedence>();
 		
@@ -1065,79 +1020,46 @@ public class AjTypeImpl<T> implements AjType<T> {
 		return ret;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getEnumConstants()
-	 */
 	public T[] getEnumConstants() {
 		return clazz.getEnumConstants();
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#getTypeParameters()
-	 */
 	public TypeVariable<Class<T>>[] getTypeParameters() {
 		return clazz.getTypeParameters();
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#isEnum()
-	 */
 	public boolean isEnum() {
 		return clazz.isEnum();
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#isInstance(java.lang.Object)
-	 */
 	public boolean isInstance(Object o) {
 		return clazz.isInstance(o);
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#isInterface()
-	 */
 	public boolean isInterface() {
 		return clazz.isInterface();
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#isLocalClass()
-	 */
 	public boolean isLocalClass() {
 		return clazz.isLocalClass() && !isAspect();
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#isMemberClass()
-	 */
 	public boolean isMemberClass() {
 		return clazz.isMemberClass() && !isAspect();
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#isArray()
-	 */
 	public boolean isArray() {
 		return clazz.isArray();
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#isPrimitive()
-	 */
 	public boolean isPrimitive() {
 		return clazz.isPrimitive();
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#isAspect()
-	 */
 	public boolean isAspect() {
 		return clazz.getAnnotation(Aspect.class) != null;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.AjType#isMemberAspect()
-	 */
 	public boolean isMemberAspect() {
 		return clazz.isMemberClass() && isAspect();
 	}
diff --git a/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareAnnotationImpl.java b/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareAnnotationImpl.java
index bcc91b987..09c592b8e 100644
--- a/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareAnnotationImpl.java
+++ b/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareAnnotationImpl.java
@@ -47,37 +47,22 @@ public class DeclareAnnotationImpl implements DeclareAnnotation {
 		this.annText = annText;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareAnnotation#getDeclaringType()
-	 */
 	public AjType<?> getDeclaringType() {
 		return this.declaringType;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareAnnotation#getKind()
-	 */
 	public Kind getKind() {
 		return this.kind;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareAnnotation#getSignaturePattern()
-	 */
 	public SignaturePattern getSignaturePattern() {
 		return this.signaturePattern;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareAnnotation#getTypePattern()
-	 */
 	public TypePattern getTypePattern() {
 		return this.typePattern;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareAnnotation#getAnnotation()
-	 */
 	public Annotation getAnnotation() {
 		return this.theAnnotation;
 	}
diff --git a/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareErrorOrWarningImpl.java b/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareErrorOrWarningImpl.java
index 5420f8274..8223d1187 100644
--- a/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareErrorOrWarningImpl.java
+++ b/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareErrorOrWarningImpl.java
@@ -35,23 +35,14 @@ public class DeclareErrorOrWarningImpl implements DeclareErrorOrWarning {
 	
 	public AjType getDeclaringType() { return this.declaringType; }
 	
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareErrorOrWarning#getPointcutExpression()
-	 */
 	public PointcutExpression getPointcutExpression() {
 		return pc;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareErrorOrWarning#getMessage()
-	 */
 	public String getMessage() {
 		return msg;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareErrorOrWarning#isError()
-	 */
 	public boolean isError() {
 		return isError;
 	}
diff --git a/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareParentsImpl.java b/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareParentsImpl.java
index 4f5720667..e33166822 100644
--- a/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareParentsImpl.java
+++ b/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareParentsImpl.java
@@ -31,10 +31,9 @@ public class DeclareParentsImpl implements DeclareParents {
 	private boolean isExtends;
 	private boolean parentsError = false;
 	
-	/**
-	 * Parents arg is a comma-separate list of type names that needs to be turned into 
-	 * AjTypes 
-	 */
+	
+	// Parents arg is a comma-separate list of type names that needs to be turned into 
+	// AjTypes 
 	public DeclareParentsImpl(String targets, String parentsAsString, boolean isExtends, AjType<?> declaring) 
 	{
 		this.targetTypesPattern = new TypePatternImpl(targets);
@@ -49,37 +48,22 @@ public class DeclareParentsImpl implements DeclareParents {
 		}
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareParents#getDeclaringType()
-	 */
 	public AjType getDeclaringType() {
 		return this.declaringType;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareParents#getTargetTypesPattern()
-	 */
 	public TypePattern getTargetTypesPattern() {
 		return this.targetTypesPattern;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareParents#isExtends()
-	 */
 	public boolean isExtends() {
 		return this.isExtends;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareParents#isImplements()
-	 */
 	public boolean isImplements() {
 		return !this.isExtends;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareParents#getParentTypes()
-	 */
 	public Type[] getParentTypes() throws ClassNotFoundException {
 		if (parentsError) {
 			throw new ClassNotFoundException(this.firstMissingTypeName);
diff --git a/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclarePrecedenceImpl.java b/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclarePrecedenceImpl.java
index 7188606c6..ea8639aec 100644
--- a/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclarePrecedenceImpl.java
+++ b/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclarePrecedenceImpl.java
@@ -41,16 +41,10 @@ public class DeclarePrecedenceImpl implements DeclarePrecedence {
 		}
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclarePrecedence#getDeclaringType()
-	 */
 	public AjType getDeclaringType() {
 		return this.declaringType;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclarePrecedence#getPrecedenceOrder()
-	 */
 	public TypePattern[] getPrecedenceOrder() {
 		return this.precedenceList;
 	}
diff --git a/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareSoftImpl.java b/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareSoftImpl.java
index 4c8ea4ead..4fb8122c6 100644
--- a/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareSoftImpl.java
+++ b/runtime/src/main/java/org/aspectj/internal/lang/reflect/DeclareSoftImpl.java
@@ -39,24 +39,15 @@ public class DeclareSoftImpl implements DeclareSoft {
 		}
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareSoft#getDeclaringType()
-	 */
 	public AjType getDeclaringType() {
 		return this.declaringType;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareSoft#getSoftenedExceptionType()
-	 */
 	public AjType getSoftenedExceptionType() throws ClassNotFoundException {
 		if (this.missingTypeName != null) throw new ClassNotFoundException(this.missingTypeName);
 		return this.exceptionType;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.DeclareSoft#getPointcutExpression()
-	 */
 	public PointcutExpression getPointcutExpression() {
 		return this.pointcut;
 	}
diff --git a/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeConstructorDeclarationImpl.java b/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeConstructorDeclarationImpl.java
index 9b80263a3..9df0c99ef 100644
--- a/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeConstructorDeclarationImpl.java
+++ b/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeConstructorDeclarationImpl.java
@@ -27,20 +27,12 @@ public class InterTypeConstructorDeclarationImpl extends
 
 	private Method baseMethod;
 	
-	/**
-	 * @param decType
-	 * @param target
-	 * @param mods
-	 */
 	public InterTypeConstructorDeclarationImpl(AjType<?> decType,
 			String target, int mods, Method baseMethod) {
 		super(decType, target, mods);
 		this.baseMethod = baseMethod;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.InterTypeConstructorDeclaration#getParameters()
-	 */
 	public AjType<?>[] getParameterTypes() {
 		Class<?>[] baseTypes = baseMethod.getParameterTypes();
 		AjType<?>[] ret = new AjType<?>[baseTypes.length-1];
@@ -50,9 +42,6 @@ public class InterTypeConstructorDeclarationImpl extends
 		return ret;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.InterTypeConstructorDeclaration#getGenericParameters()
-	 */
 	public Type[] getGenericParameterTypes() {
 		Type[] baseTypes = baseMethod.getGenericParameterTypes();
 		Type[] ret = new AjType<?>[baseTypes.length-1];
@@ -66,9 +55,6 @@ public class InterTypeConstructorDeclarationImpl extends
 		return ret;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.InterTypeConstructorDeclaration#getDeclaredExceptionTypes()
-	 */
 	public AjType<?>[] getExceptionTypes() {
 		Class<?>[] baseTypes = baseMethod.getExceptionTypes();
 		AjType<?>[] ret = new AjType<?>[baseTypes.length];
diff --git a/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeDeclarationImpl.java b/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeDeclarationImpl.java
index b4bb23aab..f091665ef 100644
--- a/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeDeclarationImpl.java
+++ b/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeDeclarationImpl.java
@@ -43,24 +43,15 @@ public class InterTypeDeclarationImpl implements InterTypeDeclaration {
 		this.modifiers = mods;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.InterTypeDeclaration#getDeclaringType()
-	 */
 	public AjType<?> getDeclaringType() {
 		return this.declaringType;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.InterTypeDeclaration#getTargetType()
-	 */
 	public AjType<?> getTargetType() throws ClassNotFoundException {
 		if (this.targetType == null) throw new ClassNotFoundException(this.targetTypeName);
 		return this.targetType;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.InterTypeDeclaration#getModifiers()
-	 */
 	public int getModifiers() {
 		return this.modifiers;
 	}
diff --git a/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeFieldDeclarationImpl.java b/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeFieldDeclarationImpl.java
index 2370919c0..f65d4b0e1 100644
--- a/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeFieldDeclarationImpl.java
+++ b/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeFieldDeclarationImpl.java
@@ -29,11 +29,6 @@ public class InterTypeFieldDeclarationImpl extends InterTypeDeclarationImpl
 	private AjType<?> type;
 	private Type genericType;
 	
-	/**
-	 * @param decType
-	 * @param target
-	 * @param mods
-	 */
 	public InterTypeFieldDeclarationImpl(AjType<?> decType, String target,
 			int mods, String name, AjType<?> type, Type genericType) {
 		super(decType, target, mods);
@@ -54,23 +49,14 @@ public class InterTypeFieldDeclarationImpl extends InterTypeDeclarationImpl
 		}
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.InterTypeFieldDeclaration#getName()
-	 */
 	public String getName() {
 		return this.name;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.InterTypeFieldDeclaration#getType()
-	 */
 	public AjType<?> getType() {
 		return this.type;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.InterTypeFieldDeclaration#getGenericType()
-	 */
 	public Type getGenericType() {
 		return this.genericType;
 	}
diff --git a/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeMethodDeclarationImpl.java b/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeMethodDeclarationImpl.java
index eb085a055..4ef079b49 100644
--- a/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeMethodDeclarationImpl.java
+++ b/runtime/src/main/java/org/aspectj/internal/lang/reflect/InterTypeMethodDeclarationImpl.java
@@ -35,11 +35,6 @@ public class InterTypeMethodDeclarationImpl extends InterTypeDeclarationImpl
 	private Type genericReturnType;
 	private AjType<?>[] exceptionTypes;
 	
-	/**
-	 * @param decType
-	 * @param target
-	 * @param mods
-	 */
 	public InterTypeMethodDeclarationImpl(AjType<?> decType, String target,
 			int mods, String name, Method itdInterMethod) {
 		super(decType, target, mods);
@@ -54,23 +49,14 @@ public class InterTypeMethodDeclarationImpl extends InterTypeDeclarationImpl
 		this.baseMethod = base;
 	}
 	
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.InterTypeMethodDeclaration#getName()
-	 */
 	public String getName() {
 		return this.name;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.InterTypeMethodDeclaration#getReturnType()
-	 */
 	public AjType<?> getReturnType() {
 		return AjTypeSystem.getAjType(baseMethod.getReturnType());
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.InterTypeMethodDeclaration#getGenericReturnType()
-	 */
 	public Type getGenericReturnType() {
 		Type gRet = baseMethod.getGenericReturnType();
 		if (gRet instanceof Class) {
@@ -79,9 +65,6 @@ public class InterTypeMethodDeclarationImpl extends InterTypeDeclarationImpl
 		return gRet;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.InterTypeMethodDeclaration#getParameters()
-	 */
 	public AjType<?>[] getParameterTypes() {
 		Class<?>[] baseTypes = baseMethod.getParameterTypes();
 		AjType<?>[] ret = new AjType<?>[baseTypes.length -parameterAdjustmentFactor];
@@ -91,9 +74,6 @@ public class InterTypeMethodDeclarationImpl extends InterTypeDeclarationImpl
 		return ret;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.InterTypeMethodDeclaration#getGenericParameters()
-	 */
 	public Type[] getGenericParameterTypes() {
 		Type[] baseTypes = baseMethod.getGenericParameterTypes();
 		Type[] ret = new AjType<?>[baseTypes.length-parameterAdjustmentFactor];
@@ -107,9 +87,6 @@ public class InterTypeMethodDeclarationImpl extends InterTypeDeclarationImpl
 		return ret;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.InterTypeMethodDeclaration#getTypeParameters()
-	 */
 	public TypeVariable<Method>[] getTypeParameters() {
 		return baseMethod.getTypeParameters();
 	}
diff --git a/runtime/src/main/java/org/aspectj/internal/lang/reflect/PerClauseImpl.java b/runtime/src/main/java/org/aspectj/internal/lang/reflect/PerClauseImpl.java
index 663a44c20..e01519914 100644
--- a/runtime/src/main/java/org/aspectj/internal/lang/reflect/PerClauseImpl.java
+++ b/runtime/src/main/java/org/aspectj/internal/lang/reflect/PerClauseImpl.java
@@ -26,9 +26,6 @@ public class PerClauseImpl implements PerClause {
 		this.kind = kind;
 	}
 	
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.PerClause#getKind()
-	 */
 	public PerClauseKind getKind() {
 		return kind;
 	}
diff --git a/runtime/src/main/java/org/aspectj/internal/lang/reflect/SignaturePatternImpl.java b/runtime/src/main/java/org/aspectj/internal/lang/reflect/SignaturePatternImpl.java
index 9820667d8..4fef6c1b9 100644
--- a/runtime/src/main/java/org/aspectj/internal/lang/reflect/SignaturePatternImpl.java
+++ b/runtime/src/main/java/org/aspectj/internal/lang/reflect/SignaturePatternImpl.java
@@ -25,9 +25,6 @@ public class SignaturePatternImpl implements SignaturePattern {
 		this.sigPattern = pattern;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.SignaturePattern#asString()
-	 */
 	public String asString() {
 		return sigPattern;
 	}
diff --git a/runtime/src/main/java/org/aspectj/internal/lang/reflect/TypePatternBasedPerClauseImpl.java b/runtime/src/main/java/org/aspectj/internal/lang/reflect/TypePatternBasedPerClauseImpl.java
index e9bb08573..f0bca173c 100644
--- a/runtime/src/main/java/org/aspectj/internal/lang/reflect/TypePatternBasedPerClauseImpl.java
+++ b/runtime/src/main/java/org/aspectj/internal/lang/reflect/TypePatternBasedPerClauseImpl.java
@@ -29,9 +29,6 @@ public class TypePatternBasedPerClauseImpl extends PerClauseImpl implements
 		this.typePattern = new TypePatternImpl(pattern);
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.TypePatternBasedPerClause#getTypePattern()
-	 */
 	public TypePattern getTypePattern() {
 		return this.typePattern;
 	}
diff --git a/runtime/src/main/java/org/aspectj/internal/lang/reflect/TypePatternImpl.java b/runtime/src/main/java/org/aspectj/internal/lang/reflect/TypePatternImpl.java
index 9973ed3bf..80b4b2ad1 100644
--- a/runtime/src/main/java/org/aspectj/internal/lang/reflect/TypePatternImpl.java
+++ b/runtime/src/main/java/org/aspectj/internal/lang/reflect/TypePatternImpl.java
@@ -25,9 +25,6 @@ public class TypePatternImpl implements TypePattern {
 		this.typePattern = pattern;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.aspectj.lang.reflect.TypePattern#asString()
-	 */
 	public String asString() {
 		return this.typePattern;
 	}
diff --git a/runtime/src/main/java/org/aspectj/lang/Aspects.java b/runtime/src/main/java/org/aspectj/lang/Aspects.java
index e82320c2e..726b7ed63 100644
--- a/runtime/src/main/java/org/aspectj/lang/Aspects.java
+++ b/runtime/src/main/java/org/aspectj/lang/Aspects.java
@@ -20,11 +20,10 @@ import java.lang.reflect.InvocationTargetException;
 /**
  * Handles generic aspectOf method when those are not available in the aspects but added later on
  * thru load time weaving.
- * <p/>
  * Aspects.aspectOf(..) is doing reflective calls to the aspect aspectOf, so for better performance
  * consider using ajc compilation of the aspects and using them as a binary dependancies in your project.
  *
- * @author <a href="mailto:alex AT gnilux DOT com">Alexandre Vasseur</a>
+ * @author Alexandre Vasseur
  */
 public class Aspects {
 
@@ -36,10 +35,9 @@ public class Aspects {
     private final static String HASASPECT = "hasAspect";
 
     /**
-     * Returns the singleton aspect or the percflow / percflowbelow associated with the current thread
-     *
-     * @param aspectClass
-     * @return
+     * @param <T> the expected class of the aspect
+     * @param aspectClass the aspect class 
+     * @return the singleton aspect or the percflow / percflowbelow associated with the current thread
      * @throws NoAspectBoundException if no such aspect
      */
     public static <T> T aspectOf(Class<T> aspectClass) throws NoAspectBoundException {
@@ -54,10 +52,10 @@ public class Aspects {
     }
 
     /**
-     * Returns the perthis / pertarget aspect
-     * @param aspectClass
-     * @param perObject
-     * @return
+     * @param <T> the expected class of the aspect
+     * @param aspectClass the aspect class 
+     * @param perObject the this/target object for which to look for an aspect instance
+     * @return the associated perthis / pertarget aspect instance
      * @throws NoAspectBoundException if no such aspect, or no aspect bound
      */
     public static <T> T aspectOf(Class<T> aspectClass, Object perObject) throws NoAspectBoundException {
@@ -72,10 +70,10 @@ public class Aspects {
     }
 
     /**
-     * Returns the pertypewithin aspect
-     * @param aspectClass
-     * @param perTypeWithin class
-     * @return
+     * @param <T> the expected class of the aspect
+     * @param aspectClass the aspect class 
+     * @param perTypeWithin the class for which to search for an aspect instance
+     * @return the associated aspect instance
      * @throws NoAspectBoundException if no such aspect, or no aspect bound
      */
     public static <T> T aspectOf(Class<T> aspectClass, Class<?> perTypeWithin) throws NoAspectBoundException {
@@ -90,10 +88,8 @@ public class Aspects {
     }
 
     /**
-     * Returns true if singleton aspect or percflow / percflowbelow aspect is bound
-     *
-     * @param aspectClass
-     * @return
+     * @param aspectClass the aspect class 
+     * @return true if singleton aspect or percflow / percflowbelow aspect is bound
      * @throws NoAspectBoundException if not bound
      */
     public static boolean hasAspect(Class<?> aspectClass) throws NoAspectBoundException {
@@ -105,10 +101,9 @@ public class Aspects {
     }
 
     /**
-     * Returns true if the perthis / pertarget aspect is bound
-     * @param aspectClass
-     * @param perObject
-     * @return
+     * @param aspectClass the aspect class 
+     * @param perObject the this/target object for which to look for an aspect instance
+     * @return true if the perthis / pertarget aspect is bound
      * @throws NoAspectBoundException if not bound
      */
     public static boolean hasAspect(Class<?> aspectClass, Object perObject) throws NoAspectBoundException {
@@ -120,10 +115,9 @@ public class Aspects {
     }
 
     /**
-     * Returns true if the pertypewithin aspect is bound
-     * @param aspectClass
+     * @param aspectClass the aspect class 
      * @param perTypeWithin class
-     * @return
+     * @return true if the pertypewithin aspect is bound
      * @throws NoAspectBoundException if not bound
      */
     public static boolean hasAspect(Class<?> aspectClass, Class<?> perTypeWithin) throws NoAspectBoundException {
diff --git a/runtime/src/main/java/org/aspectj/lang/Aspects14.java b/runtime/src/main/java/org/aspectj/lang/Aspects14.java
index b7f3a3a4b..b59374d76 100644
--- a/runtime/src/main/java/org/aspectj/lang/Aspects14.java
+++ b/runtime/src/main/java/org/aspectj/lang/Aspects14.java
@@ -20,7 +20,6 @@ import java.lang.reflect.Modifier;
  * For users working on a level of Java prior to Java5, Aspects14 handles generic aspectOf methods when they 
  * are not available in the aspects but added later on through load time weaving.  Users on Java5 should use
  * the class Aspects instead.
- * <p/>
  * Aspects14.aspectOf(..) is doing reflective calls to the aspect aspectOf, so for better performance
  * consider using ajc compilation of the aspects and using them as a binary dependancies in your project.
  */
@@ -73,7 +72,7 @@ public class Aspects14 {
      * Returns the pertypewithin aspect
      * @param aspectClass aspect class for which to discover the aspect instance
      * @param perTypeWithin class
-     * @return
+     * @return the aspect instance
      * @throws NoAspectBoundException if no such aspect, or no aspect bound
      */
     public static Object aspectOf(Class aspectClass, Class perTypeWithin) throws NoAspectBoundException {
@@ -91,7 +90,7 @@ public class Aspects14 {
      * Returns true if singleton aspect or percflow / percflowbelow aspect is bound
      *
      * @param aspectClass aspect class for which to check the aspect instance
-     * @return
+     * @return true if an aspect instance is bound
      * @throws NoAspectBoundException if not bound
      */
     public static boolean hasAspect(Class aspectClass) throws NoAspectBoundException {
@@ -105,7 +104,7 @@ public class Aspects14 {
     /**
      * Returns true if the perthis / pertarget aspect is bound
      * @param aspectClass aspect class for which to check the aspect instance
-     * @param perObject
+     * @param perObject the this/target for which to check for an aspect
      * @return true if aspect instance exists for the class/object combination
      * @throws NoAspectBoundException if not bound
      */
diff --git a/runtime/src/main/java/org/aspectj/lang/JoinPoint.java b/runtime/src/main/java/org/aspectj/lang/JoinPoint.java
index 5d66c7930..78ffce265 100644
--- a/runtime/src/main/java/org/aspectj/lang/JoinPoint.java
+++ b/runtime/src/main/java/org/aspectj/lang/JoinPoint.java
@@ -25,7 +25,7 @@ import org.aspectj.lang.reflect.SourceLocation;
  *
  * <pre>
  * aspect Logging {
- *     before(): within(com.bigboxco..*) && execution(public * *(..)) {
+ *     before(): within(com.bigboxco..*) &amp;&amp; execution(public * *(..)) {
  *         System.err.println("entering: " + thisJoinPoint);
  *         System.err.println("  w/args: " + thisJoinPoint.getArgs());
  *         System.err.println("      at: " + thisJoinPoint.getSourceLocation());
@@ -38,12 +38,12 @@ public interface JoinPoint {
     String toString();
 
     /**
-     * Returns an abbreviated string representation of the join point.
+     * @return an abbreviated string representation of the join point.
      */
     String toShortString();
 
     /**
-     * Returns an extended string representation of the join point.
+     * @return an extended string representation of the join point.
      */
     String toLongString();
 
@@ -56,46 +56,51 @@ public interface JoinPoint {
      *
      * <p> Returns null when there is no currently executing object available.
      * This includes all join points that occur in a static context.</p>
+     * 
+     * @return the currently executing object (or null if not available - e.g. static context)
      */
     Object getThis();
 
     /**
-     * <p> Returns the target object.  This will always be
+     * Returns the target object.  This will always be
      * the same object as that matched by the <code>target</code> pointcut
      * designator.  Unless you specifically need this reflective access,
      * you should use the <code>target</code> pointcut designator to
-     * get at this object for better static typing and performance.</p>
+     * get at this object for better static typing and performance.
      *
-     * <p> Returns null when there is no target object.</p>
-
+     * Returns null when there is no target object
+     * 
+     * @return the target object (or null if there isn't one)
      */
     Object getTarget();
 
     /**
-     * <p>Returns the arguments at this join point.</p>
+     * @return the arguments at this join point
      */
     Object[] getArgs();
 
-    /** Returns the signature at the join point.
-     *
+    /**
      * <code>getStaticPart().getSignature()</code> returns the same object
+     * @return the signature at the join point.
      */
     Signature getSignature();
 
-    /** <p>Returns the source location corresponding to the join point.</p>
+    /** 
      *
      *  <p>If there is no source location available, returns null.</p>
      *
      *  <p>Returns the SourceLocation of the defining class for default constructors.</p>
      *
      *  <p> <code>getStaticPart().getSourceLocation()</code> returns the same object. </p>
+     * 
+     * @return the source location corresponding to the join point.
      */
     SourceLocation getSourceLocation();
 
-    /** Returns a String representing the kind of join point.  This
-     *       String is guaranteed to be
-     *       interned. <code>getStaticPart().getKind()</code> returns
-     *       the same object.
+    /** This string is guaranteed to be interned.
+     * <code>getStaticPart().getKind()</code> returns the same object.
+     *       
+     * @return a string representing the kind of join point.
      */
     String getKind();
 
@@ -125,19 +130,19 @@ public interface JoinPoint {
      * @see JoinPoint#getStaticPart()
      */
     public interface StaticPart {
-        /** Returns the signature at the join point.  */
+        /** @return the signature at the join point.  */
         Signature getSignature();
 
-        /** <p>Returns the source location corresponding to the join point.</p>
+        /** Returns the source location corresponding to the join point.
         *
-        *  <p>If there is no source location available, returns null.</p>
+        *  If there is no source location available, returns null.
         *
-        *  <p>Returns the SourceLocation of the defining class for default constructors.</p>
+        *  @return the SourceLocation of the defining class for default constructors
         */
         SourceLocation getSourceLocation();
 
-        /** <p> Returns a String representing the kind of join point.  This String
-        *       is guaranteed to be interned</p>
+        /** @return a string representing the kind of join point.  This String
+        *       is guaranteed to be interned
         */
         String getKind();
         
@@ -165,12 +170,12 @@ public interface JoinPoint {
         String toString();
 
         /**
-        * Returns an abbreviated string representation of the join point
+        * @return an abbreviated string representation of the join point
         */
         String toShortString();
 
         /**
-        * Returns an extended string representation of the join point
+        * @return an extended string representation of the join point
         */
         String toLongString();
     }
@@ -178,7 +183,7 @@ public interface JoinPoint {
     public interface EnclosingStaticPart extends StaticPart {}
 
     /**
-     * Returns an object that encapsulates the static parts of this join point.
+     * @return an object that encapsulates the static parts of this join point.
      */
     StaticPart getStaticPart();
 
diff --git a/runtime/src/main/java/org/aspectj/lang/ProceedingJoinPoint.java b/runtime/src/main/java/org/aspectj/lang/ProceedingJoinPoint.java
index 5bbc2df85..d75aa4df4 100644
--- a/runtime/src/main/java/org/aspectj/lang/ProceedingJoinPoint.java
+++ b/runtime/src/main/java/org/aspectj/lang/ProceedingJoinPoint.java
@@ -16,32 +16,31 @@ import org.aspectj.runtime.internal.AroundClosure;
 /**
  * ProceedingJoinPoint exposes the proceed(..) method in order to support around advice in @AJ aspects
  *
- * @author <a href="mailto:alex AT gnilux DOT com">Alexandre Vasseur</a>
+ * @author Alexandre Vasseur
  */
 public interface ProceedingJoinPoint extends JoinPoint {
 
     /**
-     * The joinpoint needs to know about its closure so that proceed can delegate to closure.run()
-     * <p/>
+     * The joinpoint needs to know about its closure so that proceed can delegate to closure.run().
      * This internal method should not be called directly, and won't be visible to the end-user when
-     * packed in a jar (synthetic method)
+     * packed in a jar (synthetic method).
      *
-     * @param arc
+     * @param arc the around closure to associate with this joinpoint
      */
     void set$AroundClosure(AroundClosure arc);
 
     /**
      * Proceed with the next advice or target method invocation
      *
-     * @return
-     * @throws Throwable
+     * @return the result of proceeding
+     * @throws Throwable if the invoked proceed throws anything
      */
     public Object proceed() throws Throwable;
 
     /**
-     * Proceed with the next advice or target method invocation
-     * <p/>
-     * <p>Unlike code style, proceed(..) in annotation style places different requirements on the 
+     * Proceed with the next advice or target method invocation.
+     *
+     * Unlike code style, proceed(..) in annotation style places different requirements on the 
      * parameters passed to it.  The proceed(..) call takes, in this order:
      * <ul>
      * <li> If 'this()' was used in the pointcut for binding, it must be passed first in proceed(..).
@@ -52,14 +51,13 @@ public interface ProceedingJoinPoint extends JoinPoint {
      * if a subset of arguments were bound or the ordering was changed in the advice signature, 
      * the proceed(..) calls takes all of them in the right order for the join point. 
      * </ul>
-     * <p>Since proceed(..) in this case takes an Object array, AspectJ cannot do as much 
+     * Since proceed(..) in this case takes an Object array, AspectJ cannot do as much 
      * compile time checking as it can for code style. If the rules above aren't obeyed 
      * then it will unfortunately manifest as a runtime error. 
-     * </p>
      *
-     * @param args
-     * @return
-     * @throws Throwable
+     * @param args the arguments to proceed with
+     * @return the result of proceeding
+     * @throws Throwable if the invoked proceed throws anything
      */
     public Object proceed(Object[] args) throws Throwable;
 
diff --git a/runtime/src/main/java/org/aspectj/lang/Signature.java b/runtime/src/main/java/org/aspectj/lang/Signature.java
index 5bc008433..cd1cd4aac 100644
--- a/runtime/src/main/java/org/aspectj/lang/Signature.java
+++ b/runtime/src/main/java/org/aspectj/lang/Signature.java
@@ -24,7 +24,7 @@ package org.aspectj.lang;
  * aspect Logging {
  *     Logger logger = Logger.getLogger("MethodEntries");
  * 
- *     before(): within(com.bigboxco..*) && execution(public * *(..)) {
+ *     before(): within(com.bigboxco..*) &amp;&amp; execution(public * *(..)) {
  *         Signature sig = thisJoinPoint.getSignature();
  *         logger.entering(sig.getDeclaringType().getName(),
  *                         sig.getName());
@@ -43,19 +43,20 @@ package org.aspectj.lang;
  */
 public interface Signature {
     String toString();
+
     /**
-     * Returns an abbreviated string representation of this signature.
+     * @return an abbreviated string representation of this signature.
      */
     String toShortString();
 
     /**
-     * Returns an extended string representation of this signature.
+     * @return an extended string representation of this signature.
      */
     String toLongString();
 
 
     /**
-     * Returns the identifier part of this signature.  For methods this
+     * @return the identifier part of this signature.  For methods this
      * will return the method name.
      * 
      * @see java.lang.reflect.Member#getName
@@ -74,6 +75,7 @@ public interface Signature {
      *     java.lang.reflect.Modifier.toString(sig.getModifiers());
      * </pre>
      * 
+     * @return the modifiers on this signature represented as an int
      * @see java.lang.reflect.Member#getModifiers
      * @see java.lang.reflect.Modifier
      */
@@ -89,14 +91,16 @@ public interface Signature {
      * <p>For consistency with <code>java.lang.reflect.Member</code>, this
      * method should have been named <code>getDeclaringClass()</code>.</p>
      * 
+     * @return the class, interface or aspect that declared this member
      * @see java.lang.reflect.Member#getDeclaringClass
      */
     Class  getDeclaringType();
     
     /**
-     * Returns the fully-qualified name of the declaring type. This is
-     * equivalent to calling getDeclaringType().getName(), but caches
+     * This is equivalent to calling getDeclaringType().getName(), but caches
      * the result for greater efficiency.
+     * 
+     * @return the fully qualified name of the declaring type
      */
     String getDeclaringTypeName();
 }
diff --git a/runtime/src/main/java/org/aspectj/lang/annotation/AdviceName.java b/runtime/src/main/java/org/aspectj/lang/annotation/AdviceName.java
index 779e7fee6..62f60916e 100644
--- a/runtime/src/main/java/org/aspectj/lang/annotation/AdviceName.java
+++ b/runtime/src/main/java/org/aspectj/lang/annotation/AdviceName.java
@@ -25,7 +25,7 @@ import java.lang.annotation.ElementType;
 public @interface AdviceName {
 
     /**
-     * The name of the advice
+     * @return the name of the advice
      */
     String value();
 }
diff --git a/runtime/src/main/java/org/aspectj/lang/annotation/After.java b/runtime/src/main/java/org/aspectj/lang/annotation/After.java
index 286f9c7e5..43d9edc57 100644
--- a/runtime/src/main/java/org/aspectj/lang/annotation/After.java
+++ b/runtime/src/main/java/org/aspectj/lang/annotation/After.java
@@ -19,14 +19,14 @@ import java.lang.annotation.RetentionPolicy;
 /**
  * After finally advice
  *
- * @author <a href="mailto:alex AT gnilux DOT com">Alexandre Vasseur</a>
+ * @author Alexandre Vasseur
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface After {
 
     /**
-     * The pointcut expression where to bind the advice
+     * @return the pointcut expression where to bind the advice
      */
     String value();
     
@@ -36,6 +36,8 @@ public @interface After {
      * Under these circumstances only, it is necessary to provide the arg names in 
      * the annotation - these MUST duplicate the names used in the annotated method.
      * Format is a simple comma-separated list.
+     * 
+     * @return the argument names (should duplicate the names used for the annotated method parameters)
      */
     String argNames() default "";
 }
diff --git a/runtime/src/main/java/org/aspectj/lang/annotation/AfterReturning.java b/runtime/src/main/java/org/aspectj/lang/annotation/AfterReturning.java
index 397c48fc6..99e7f99f4 100644
--- a/runtime/src/main/java/org/aspectj/lang/annotation/AfterReturning.java
+++ b/runtime/src/main/java/org/aspectj/lang/annotation/AfterReturning.java
@@ -19,24 +19,24 @@ import java.lang.annotation.RetentionPolicy;
 /**
  * After returning advice
  *
- * @author <a href="mailto:alex AT gnilux DOT com">Alexandre Vasseur</a>
+ * @author Alexandre Vasseur
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface AfterReturning {
 
     /**
-     * The pointcut expression where to bind the advice
+     * @return the pointcut expression where to bind the advice
      */
     String value() default "";
 
     /**
-     * The pointcut expression where to bind the advice, overrides "value" when specified
+     * @return the pointcut expression where to bind the advice, overrides "value" when specified
      */
     String pointcut() default "";
 
     /**
-     * The name of the argument in the advice signature to bind the returned value to
+     * @return the name of the argument in the advice signature to bind the returned value to
      */
     String returning() default "";
     
@@ -46,6 +46,7 @@ public @interface AfterReturning {
      * Under these circumstances only, it is necessary to provide the arg names in 
      * the annotation - these MUST duplicate the names used in the annotated method.
      * Format is a simple comma-separated list.
+     * @return the argument names (that should match names used in the annotated method)
      */
     String argNames() default "";
 
diff --git a/runtime/src/main/java/org/aspectj/lang/annotation/AfterThrowing.java b/runtime/src/main/java/org/aspectj/lang/annotation/AfterThrowing.java
index 7b4d8212c..32d0f7944 100644
--- a/runtime/src/main/java/org/aspectj/lang/annotation/AfterThrowing.java
+++ b/runtime/src/main/java/org/aspectj/lang/annotation/AfterThrowing.java
@@ -19,24 +19,24 @@ import java.lang.annotation.RetentionPolicy;
 /**
  * After throwing advice
  *
- * @author <a href="mailto:alex AT gnilux DOT com">Alexandre Vasseur</a>
+ * @author Alexandre Vasseur
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface AfterThrowing {
 
     /**
-     * The pointcut expression where to bind the advice
+     * @return the pointcut expression where to bind the advice
      */
     String value() default "";
 
     /**
-     * The pointcut expression where to bind the advice, overrides "value" when specified
+     * @return the pointcut expression where to bind the advice, overrides "value" when specified
      */
     String pointcut() default "";
 
     /**
-     * The name of the argument in the advice signature to bind the thrown exception to
+     * @return the name of the argument in the advice signature to bind the thrown exception to
      */
     String throwing() default "";
     
@@ -46,6 +46,7 @@ public @interface AfterThrowing {
      * Under these circumstances only, it is necessary to provide the arg names in 
      * the annotation - these MUST duplicate the names used in the annotated method.
      * Format is a simple comma-separated list.
+     * @return the argument names (that should match names used in the annotated method)
      */
     String argNames() default "";
 
diff --git a/runtime/src/main/java/org/aspectj/lang/annotation/Around.java b/runtime/src/main/java/org/aspectj/lang/annotation/Around.java
index 253e865f6..36510c70f 100644
--- a/runtime/src/main/java/org/aspectj/lang/annotation/Around.java
+++ b/runtime/src/main/java/org/aspectj/lang/annotation/Around.java
@@ -19,14 +19,14 @@ import java.lang.annotation.RetentionPolicy;
 /**
  * Around advice
  *
- * @author <a href="mailto:alex AT gnilux DOT com">Alexandre Vasseur</a>
+ * @author Alexandre Vasseur
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface Around {
 
     /**
-     * The pointcut expression where to bind the advice
+     * @return the pointcut expression where to bind the advice
      */
     String value();
     
@@ -36,6 +36,7 @@ public @interface Around {
      * Under these circumstances only, it is necessary to provide the arg names in 
      * the annotation - these MUST duplicate the names used in the annotated method.
      * Format is a simple comma-separated list.
+     * @return the argument names (should match the names on the annotated method)
      */
     String argNames() default "";
 
diff --git a/runtime/src/main/java/org/aspectj/lang/annotation/Aspect.java b/runtime/src/main/java/org/aspectj/lang/annotation/Aspect.java
index d45e85c84..7e50fa75b 100644
--- a/runtime/src/main/java/org/aspectj/lang/annotation/Aspect.java
+++ b/runtime/src/main/java/org/aspectj/lang/annotation/Aspect.java
@@ -19,15 +19,14 @@ import java.lang.annotation.RetentionPolicy;
 /**
  * Aspect declaration
  *
- * @author <a href="mailto:alex AT gnilux DOT com">Alexandre Vasseur</a>
+ * @author Alexandre Vasseur
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 public @interface Aspect {
 
     /**
-     * Per clause expression, defaults to singleton aspect
-     * <p/>
+     * @return the per clause expression, defaults to singleton aspect.
      * Valid values are "" (singleton), "perthis(...)", etc
      */
     public String value() default "";
diff --git a/runtime/src/main/java/org/aspectj/lang/annotation/Before.java b/runtime/src/main/java/org/aspectj/lang/annotation/Before.java
index fe4b372c1..db1ec5e2a 100644
--- a/runtime/src/main/java/org/aspectj/lang/annotation/Before.java
+++ b/runtime/src/main/java/org/aspectj/lang/annotation/Before.java
@@ -19,14 +19,14 @@ import java.lang.annotation.RetentionPolicy;
 /**
  * Before advice
  *
- * @author <a href="mailto:alex AT gnilux DOT com">Alexandre Vasseur</a>
+ * @author Alexandre Vasseur
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface Before {
 
     /**
-     * The pointcut expression where to bind the advice
+     * @return the pointcut expression where to bind the advice
      */
     String value();
     
@@ -36,6 +36,8 @@ public @interface Before {
      * Under these circumstances only, it is necessary to provide the arg names in 
      * the annotation - these MUST duplicate the names used in the annotated method.
      * Format is a simple comma-separated list.
+     * 
+     * @return the argument names (should match the annotated method parameter names)
      */
     String argNames() default "";
 
diff --git a/runtime/src/main/java/org/aspectj/lang/annotation/DeclareAnnotation.java b/runtime/src/main/java/org/aspectj/lang/annotation/DeclareAnnotation.java
index ffecb91a2..f0c564dd3 100644
--- a/runtime/src/main/java/org/aspectj/lang/annotation/DeclareAnnotation.java
+++ b/runtime/src/main/java/org/aspectj/lang/annotation/DeclareAnnotation.java
@@ -17,14 +17,14 @@ import java.lang.annotation.Target;
 import java.lang.annotation.ElementType;
 
 /**
- * @author <a href="mailto:alex AT gnilux DOT com">Alexandre Vasseur</a>
+ * @author Alexandre Vasseur
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.CONSTRUCTOR})
 public @interface DeclareAnnotation {
 
     /**
-     * pointcut (type pattern for type, or method/ctor/field signature pattern)
+     * @return the pointcut (type pattern for type, or method/ctor/field signature pattern)
      */
     public String value();
     
diff --git a/runtime/src/main/java/org/aspectj/lang/annotation/DeclareError.java b/runtime/src/main/java/org/aspectj/lang/annotation/DeclareError.java
index 9f3a045ee..0d0d1c055 100644
--- a/runtime/src/main/java/org/aspectj/lang/annotation/DeclareError.java
+++ b/runtime/src/main/java/org/aspectj/lang/annotation/DeclareError.java
@@ -27,7 +27,7 @@ import java.lang.annotation.Target;
 @Target(ElementType.FIELD)
 public @interface DeclareError {
     /**
-     * The pointcut expression where to bind the error (don't use if, formal bindings, cflow etc)
+     * @return the pointcut expression where to bind the error (don't use if, formal bindings, cflow etc)
      */
 	String value();
 }
diff --git a/runtime/src/main/java/org/aspectj/lang/annotation/DeclareMixin.java b/runtime/src/main/java/org/aspectj/lang/annotation/DeclareMixin.java
index f44c68195..4a7d35085 100644
--- a/runtime/src/main/java/org/aspectj/lang/annotation/DeclareMixin.java
+++ b/runtime/src/main/java/org/aspectj/lang/annotation/DeclareMixin.java
@@ -18,7 +18,6 @@ import java.lang.annotation.Target;
 
 /**
  * DeclareMixin annotation - see design and usage in https://bugs.eclipse.org/bugs/show_bug.cgi?id=266552
- * 
  * <p>
  * Attached to a factory method, this annotation indicates that any types matching the pattern specified in the annotation value
  * will have new methods mixed in. The methods will be selected based on a combination of the return type of the factory method,
@@ -29,12 +28,12 @@ import java.lang.annotation.Target;
 public @interface DeclareMixin {
 
 	/**
-	 * The target types expression
+	 * @return the target types expression
 	 */
 	String value();
 
 	/**
-	 * Array of interfaces that are to be mixed in. This is optional and if not specified the return type of the annotated method
+	 * @return array of interfaces that are to be mixed in. This is optional and if not specified the return type of the annotated method
 	 * will be used to determine the interface to mix in.
 	 */
 	Class[] interfaces() default { Object.class };
diff --git a/runtime/src/main/java/org/aspectj/lang/annotation/DeclareParents.java b/runtime/src/main/java/org/aspectj/lang/annotation/DeclareParents.java
index b7c2452e2..9f2c02a4f 100644
--- a/runtime/src/main/java/org/aspectj/lang/annotation/DeclareParents.java
+++ b/runtime/src/main/java/org/aspectj/lang/annotation/DeclareParents.java
@@ -24,7 +24,7 @@ import java.lang.annotation.RetentionPolicy;
 public @interface DeclareParents {
 
     /**
-     * The target types expression
+     * @return the target types expression
      */
     String value();
 
@@ -33,6 +33,8 @@ public @interface DeclareParents {
      * of interface members (equivalent to defining
      * a set of interface member ITDs for the
      * public methods of the interface).
+     * 
+     * @return define the default implementation of interface members (should always be specified)
      */
     Class defaultImpl() default DeclareParents.class;
 
diff --git a/runtime/src/main/java/org/aspectj/lang/annotation/DeclarePrecedence.java b/runtime/src/main/java/org/aspectj/lang/annotation/DeclarePrecedence.java
index e1a048819..2c74c8a99 100644
--- a/runtime/src/main/java/org/aspectj/lang/annotation/DeclarePrecedence.java
+++ b/runtime/src/main/java/org/aspectj/lang/annotation/DeclarePrecedence.java
@@ -19,14 +19,14 @@ import java.lang.annotation.RetentionPolicy;
 /**
  * Aspect precedence declaration
  *
- * @author <a href="mailto:alex AT gnilux DOT com">Alexandre Vasseur</a>
+ * @author Alexandre Vasseur
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 public @interface DeclarePrecedence {
 
     /**
-     * The precedence pattern list
+     * @return the precedence pattern list
      */
     String value();
 
diff --git a/runtime/src/main/java/org/aspectj/lang/annotation/DeclareWarning.java b/runtime/src/main/java/org/aspectj/lang/annotation/DeclareWarning.java
index 446ac786a..17cf2df74 100644
--- a/runtime/src/main/java/org/aspectj/lang/annotation/DeclareWarning.java
+++ b/runtime/src/main/java/org/aspectj/lang/annotation/DeclareWarning.java
@@ -27,7 +27,7 @@ import java.lang.annotation.Target;
 @Target(ElementType.FIELD)
 public @interface DeclareWarning {
     /**
-     * The pointcut expression where to bind the error (don't use if, formal bindings, cflow etc)
+     * @return the pointcut expression where to bind the error (don't use if, formal bindings, cflow etc)
      */
 	String value();
 }
diff --git a/runtime/src/main/java/org/aspectj/lang/annotation/Pointcut.java b/runtime/src/main/java/org/aspectj/lang/annotation/Pointcut.java
index 6fae1e8b9..938a50a80 100644
--- a/runtime/src/main/java/org/aspectj/lang/annotation/Pointcut.java
+++ b/runtime/src/main/java/org/aspectj/lang/annotation/Pointcut.java
@@ -19,14 +19,14 @@ import java.lang.annotation.RetentionPolicy;
 /**
  * Pointcut declaration
  *
- * @author <a href="mailto:alex AT gnilux DOT com">Alexandre Vasseur</a>
+ * @author Alexandre Vasseur
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface Pointcut {
 
     /**
-     * The pointcut expression
+     * @return the pointcut expression
      * We allow "" as default for abstract pointcut
      */
     String value() default "";
@@ -37,6 +37,8 @@ public @interface Pointcut {
      * Under these circumstances only, it is necessary to provide the arg names in 
      * the annotation - these MUST duplicate the names used in the annotated method.
      * Format is a simple comma-separated list.
+     * 
+     * @return argNames the argument names (should match those in the annotated method)
      */
     String argNames() default "";
 }
diff --git a/runtime/src/main/java/org/aspectj/lang/annotation/control/CodeGenerationHint.java b/runtime/src/main/java/org/aspectj/lang/annotation/control/CodeGenerationHint.java
index 7fe9dea24..e7d92c301 100644
--- a/runtime/src/main/java/org/aspectj/lang/annotation/control/CodeGenerationHint.java
+++ b/runtime/src/main/java/org/aspectj/lang/annotation/control/CodeGenerationHint.java
@@ -26,7 +26,7 @@ import java.lang.annotation.RetentionPolicy;
 public @interface CodeGenerationHint {
 
 	/**
-	 * Defines the name suffix to use for a generated member representing an if pointcut (prefix will be 'ajc$if$').
+	 * @return the name suffix to use for a generated member representing an if pointcut (prefix will be 'ajc$if$').
 	 * If left blank, a suffix will be generated.
 	 */
     String ifNameSuffix() default "";
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/Advice.java b/runtime/src/main/java/org/aspectj/lang/reflect/Advice.java
index 03be6c7f1..3c00e74ad 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/Advice.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/Advice.java
@@ -19,41 +19,42 @@ import java.lang.reflect.Type;
 public interface Advice {
 
 	/**
-	 * The declaring aspect
+	 * @return the declaring aspect
 	 */
 	AjType getDeclaringType();
 	
 	/**
-	 * The kind of advice (before, after-returning, after-throwing, etc.)
+	 * @return the kind of advice (before, after-returning, after-throwing, etc.)
 	 */
 	AdviceKind getKind();
 	
 	/**
-	 * Returns the advice name, or the empty string if the advice is anonymous.
 	 * If using the @AspectJ annotations, the advice name is the name of the
 	 * annotated advice method. If using the code style, the advice is
 	 * anonymous, unless the advice is annotated with the @AdviceName annotation,
-	 * in which case the name given in the annotation is returned. 
+	 * in which case the name given in the annotation is returned.
+	 * 
+	 * @return the advice name, or the empty string if the advice is anonymous.
 	 */
 	String getName();
 	
 	/**
-	 * The advice parameters
+	 * @return the advice parameters
 	 */
 	AjType<?>[] getParameterTypes();
 	
 	/**
-	 * The generic parameter types, @see java.lang.reflect.Method.getGenericParameterTypes
+	 * @return the generic parameter types, @see java.lang.reflect.Method.getGenericParameterTypes
 	 */
 	Type[] getGenericParameterTypes();
 	
 	/**
-	 * The declared thrown exceptions by the advice
+	 * @return the declared thrown exceptions by the advice
 	 */
 	AjType<?>[] getExceptionTypes();
 	
 	/**
-	 * The pointcut expression associated with the advice declaration.
+	 * @return the pointcut expression associated with the advice declaration.
 	 */
 	PointcutExpression getPointcutExpression();
 }
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/AjType.java b/runtime/src/main/java/org/aspectj/lang/reflect/AjType.java
index 5e26a7d27..2ceddb952 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/AjType.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/AjType.java
@@ -25,289 +25,332 @@ import java.lang.reflect.TypeVariable;
 public interface AjType<T> extends Type, AnnotatedElement {
 	
 	/**
-	 * The name of this type, in the same format as returned by Class.getName()
+	 * @return the name of this type, in the same format as returned by Class.getName()
 	 */
 	public String getName();
 	
 	/**
-	 * The package in which this type is declared
+	 * @return the package in which this type is declared
 	 */
 	public Package getPackage();
 	
 	/**
-	 * The interfaces implemented by this type
+	 * @return the interfaces implemented by this type
 	 */
 	public AjType<?>[] getInterfaces();
 		
 	/**
-	 * The modifiers declared for this type. The return value can be interpreted
+	 * @return the modifiers declared for this type. The return value can be interpreted
 	 * using java.lang.reflect.Modifier
 	 */
 	public int getModifiers();
 	
 	/**
-	 * The java.lang.Class that corresponds to this AjType
+	 * @return the java.lang.Class that corresponds to this AjType
 	 */
 	public Class<T> getJavaClass();
 
 	// scope
 	
 	/**
-	 * The supertype of this type. If this type represents Object or a primitive type
+	 * @return the supertype of this type. If this type represents Object or a primitive type
 	 * then null is returned.
 	 */
 	public AjType<?> getSupertype();
 
 	/**
-	 * The generic supertype of this type, as defined by Class.getGenericSupertype
+	 * @return the generic supertype of this type, as defined by Class.getGenericSupertype
 	 */
 	public Type getGenericSupertype();
 
 	/**
-	 * If this type represents a local or anonymous type declared within a method, return 
-	 * then enclosing Method object.
+	 * @return the enclosing Method if this type represents a local or anonymous type declared within a method
 	 */
 	public Method getEnclosingMethod();
 	
 	/**
-	 * If this type represents a local or anonymous type declared within a constructor, return 
-	 * then enclosing Method object.
+	 * @return the enclosing Method if this type represents a local or anonymous type declared within a constructor
 	 */
 	public Constructor getEnclosingConstructor();
 
 	/**
-	 * Returns the immediately enclosing type of this type.
+	 * @return the immediately enclosing type of this type.
 	 */
 	public AjType<?> getEnclosingType();
 	
 	/**
-	 * If this type is a member of another type, return the AjType representing the type
-	 * in which it was declared.
+	 * @return the AjType representing the typei n which it was declared (if this type is a member of another type)
 	 */
 	public AjType<?> getDeclaringType();
 
 	/**
-	 * If this type represents an aspect, returns the associated per-clause.
-	 * Returns null for non-aspect types.
+	 * @return the per-clause if this is an aspect, otherwise null
 	 */
 	public PerClause getPerClause(); 
 	
 	// inner types
 	/**
-	 * Returns an array containing all the public types that are members of this type
+	 * @return an array containing all the public types that are members of this type
 	 */
 	public AjType<?>[] getAjTypes();
 	
 	/**
-	 * Returns an array containing all the types declared by this type
+	 * @return an array containing all the types declared by this type
 	 */
 	public AjType<?>[] getDeclaredAjTypes();
 	
 	// constructors
 	
 	/**
-	 * Returns the constructor object for the specified public constructor of this type
+	 * @param parameterTypes the types of the constructor parameters
+	 * @return the constructor object for the specified public constructor of this type
+	 * @throws NoSuchMethodException if constructor not found
 	 */
 	public Constructor getConstructor(AjType<?>... parameterTypes) throws NoSuchMethodException;
 	
 	/**
-	 * Returns all of the public constructors of this type
+	 * @return all of the public constructors of this type
 	 */
 	public Constructor[] getConstructors();
 	
 	/**
-	 * Returns the constructor object for the specified constructor of this type
+	 * @param parameterTypes the types of the constructor parameters
+	 * @return the constructor object for the specified constructor of this type
+	 * @throws NoSuchMethodException if constructor not found
 	 */
 	public Constructor getDeclaredConstructor(AjType<?>... parameterTypes) throws NoSuchMethodException;
 
 	/**
-	 * Returns all the constructors declared in this type
+	 * @return all the constructors declared in this type
 	 */
 	public Constructor[] getDeclaredConstructors();
 	
 	// fields
 	
 	/**
-	 * Return the field declared in this type with the given name
+	 * @param name the field name
+	 * @return the declared field
+	 * @throws NoSuchFieldException if no field of that name is found
 	 */
 	public Field getDeclaredField(String name) throws NoSuchFieldException;
 	
 	/** 
-	 * Returns all the fields declared in this type
+	 * @return all the fields declared in this type
 	 */
 	public Field[] getDeclaredFields();
 	
 	/**
-	 * Return the public field with the given name 
+	 * @param name the field name
+	 * @return the public field with the given name 
+	 * @throws NoSuchFieldException if field not found
 	 */
 	public Field getField(String name) throws NoSuchFieldException;
 	
 	/**
-	 * Return the public fields declared by this type
+	 * @return the public fields declared by this type
 	 */
 	public Field[] getFields();
 	
 	// methods
 
 	/**
-	 * Return the method object for the specified method declared in this type
+	 * @param name the method name
+	 * @param parameterTypes the types of the method parameters
+	 * @return the method object for the specified method declared in this type
+	 * @throws NoSuchMethodException if the method cannot be found
 	 */
 	public Method getDeclaredMethod(String name, AjType<?>... parameterTypes) throws NoSuchMethodException;
 	
 	/**
-	 * Return the method object for the specified public method declared in this type 
+	 * @param name the method name
+	 * @param parameterTypes the types of the method parameters
+	 * @return the method object for the specified public method declared in this type 
+	 * @throws NoSuchMethodException if the method cannot be found
 	 */
 	public Method getMethod(String name, AjType<?>... parameterTypes) throws NoSuchMethodException;
 	
 	/**
-	 * Return all the methods declared by this type
+	 * @return all the methods declared by this type
 	 */
 	public Method[] getDeclaredMethods();
 	
 	/**
-	 * Returns all the public methods of this type
+	 * @return all the public methods of this type
 	 */
 	public Method[] getMethods();
 	
 	// pointcuts
 	
 	/**
-	 * Return the pointcut object representing the specified pointcut declared by this type
+	 * @param name the pointcut name
+	 * @return the pointcut object representing the specified pointcut declared by this type
+	 * @throws NoSuchPointcutException if no pointcut of that name can be found
 	 */
 	public Pointcut getDeclaredPointcut(String name) throws NoSuchPointcutException;
 	
 	/**
-	 * Return the pointcut object representing the specified public pointcut
+	 * @param name the pointcut name
+	 * @return the pointcut object representing the specified public pointcut
+	 * @throws NoSuchPointcutException if no pointcut of that name can be found
 	 */
 	public Pointcut getPointcut(String name) throws NoSuchPointcutException;
 
 	/**
-	 * Returns all of the pointcuts declared by this type
+	 * @return all of the pointcuts declared by this type
 	 */
 	public Pointcut[] getDeclaredPointcuts();
 
 	/**
-	 * Returns all of the public pointcuts of this type
+	 * @return all of the public pointcuts of this type
 	 */
 	public Pointcut[] getPointcuts();
 	
 	// advice
 
 	/**
-	 * Returns all of the advice declared by this type, of an advice kind contained in the
+	 * @param ofTypes the {@link AdviceKind}s of interest
+	 * @return all of the advice declared by this type, of an advice kind contained in the
 	 * parameter list.
 	 */
 	public Advice[] getDeclaredAdvice(AdviceKind... ofTypes);
 	
 	/**
-	 * Returns all of the advice for this type, of an advice kind contained in the parameter
+	 * @param ofTypes the {@link AdviceKind}s of interest
+	 * @return all of the advice for this type, of an advice kind contained in the parameter
 	 * list. 
 	 */
 	public Advice[] getAdvice(AdviceKind... ofTypes);
 	
 	/**
-	 * Returns the advice with the given name. For an @AspectJ declared advice member,
+	 * For an annotation style advice member,
 	 * this is the name of the annotated method. For a code-style advice declaration, this
 	 * is the name given in the @AdviceName annotation if present.
+	 * 
+	 * @param name the advice name
+	 * @return the advice with the given name.
+	 * @throws NoSuchAdviceException if no advice can be found with that name
 	 */
 	public Advice getAdvice(String name) throws NoSuchAdviceException;
 	
-	/**
-	 * Returns the advice declared in this type with the given name. For an @AspectJ declared advice member,
+	/** For an annotation style advice member,
 	 * this is the name of the annotated method. For a code-style advice declaration, this
 	 * is the name given in the @AdviceName annotation if present.
+	 * 
+	 * @param name the advice name
+	 * @return the advice declared in this type with the given name.
+	 * @throws NoSuchAdviceException if no advice can be found with that name
 	 */
 	public Advice getDeclaredAdvice(String name) throws NoSuchAdviceException;
 		
 	// inter-type declarations
 	
 	/**
-	 * Return the inter-type method declared by this type matching the given specification
+	 * @param name the method name
+	 * @param target the target of the inter-type declaration
+	 * @param parameterTypes the types of the inter-type method declaration
+	 * @return the inter-type method declared by this type matching the given specification
+	 * @throws NoSuchMethodException if the inter-type declaration cannot be found
 	 */
 	public InterTypeMethodDeclaration getDeclaredITDMethod(String name, AjType<?> target, AjType<?>... parameterTypes) throws NoSuchMethodException;
 	
 	/**
-	 * Return all of the inter-type methods declared by this type
+	 * @return all of the inter-type methods declared by this type
 	 */
 	public InterTypeMethodDeclaration[] getDeclaredITDMethods();
 
 	/**
-	 * Return the public inter-type method of this type matching the given specification
+	 * @param name the method name
+	 * @param target the target of the inter-type declaration
+	 * @param parameterTypes the types of the inter-type method declaration
+	 * @return the public inter-type method of this type matching the given specification
+	 * @throws NoSuchMethodException if the inter-type declaration cannot be found
 	 */
 	public InterTypeMethodDeclaration getITDMethod(String name, AjType<?> target, AjType<?>... parameterTypes) throws NoSuchMethodException;
 	
 	/**
-	 * Return all of the public inter-type declared methods of this type
+	 * @return all of the public inter-type declared methods of this type
 	 */
 	public InterTypeMethodDeclaration[] getITDMethods();
 		
 	/**
-	 * Return the inter-type constructor declared by this type matching the given specification
+	 * @param target the target of the inter-type constructor of interest
+	 * @param parameterTypes the types of the parameter of the inter-type constructor of interest
+	 * @return the inter-type constructor declared by this type matching the given specification
+	 * @throws NoSuchMethodException if the inter-type declaration cannot be found
 	 */
 	public InterTypeConstructorDeclaration getDeclaredITDConstructor(AjType<?> target, AjType<?>... parameterTypes) throws NoSuchMethodException;
 	
 	/**
-	 * Returns all of the inter-type constructors declared by this type
+	 * @return all of the inter-type constructors declared by this type
 	 */
 	public InterTypeConstructorDeclaration[] getDeclaredITDConstructors();
 
 	/**
-	 * Return the public inter-type constructor matching the given specification
+	 * @param target the target of the inter-type constructor of interest
+	 * @param parameterTypes the types of the parameter of the inter-type constructor of interest
+	 * @return the public inter-type constructor matching the given specification
+	 * @throws NoSuchMethodException if the inter-type declaration cannot be found
 	 */
 	public InterTypeConstructorDeclaration getITDConstructor(AjType<?> target, AjType<?>... parameterTypes) throws NoSuchMethodException;
 
 	/**
-	 * Return all of the public inter-type constructors of this type
+	 * @return all of the public inter-type constructors of this type
 	 */
 	public InterTypeConstructorDeclaration[] getITDConstructors();
 
 	/**
-	 * Return the inter-type field declared in this type with the given specification
+	 * @param name the field name
+	 * @param target the target type for the inter-type declaration
+	 * @return the inter-type field declared in this type with the given specification
+	 * @throws NoSuchFieldException if the inter-type declaration cannot be found
 	 */
 	public InterTypeFieldDeclaration getDeclaredITDField(String name, AjType<?> target) throws NoSuchFieldException;
 
 	/**
-	 * Return all of the inter-type fields declared in this type
+	 * @return all of the inter-type fields declared in this type
 	 */
 	public InterTypeFieldDeclaration[] getDeclaredITDFields();
 
 	/**
-	 * Return the public inter-type field matching the given specification
+	 * @param name the field name
+	 * @param target the target type for the inter-type declaration
+	 * @return the public inter-type field matching the given specification
+	 * @throws NoSuchFieldException if the inter-type declaration cannot be found
 	 */
 	public InterTypeFieldDeclaration getITDField(String name, AjType<?> target) throws NoSuchFieldException;
 
 	/**
-	 * Return all of the public inter-type fields for this type
+	 * @return all of the public inter-type fields for this type
 	 */
 	public InterTypeFieldDeclaration[] getITDFields();
 		
 	// declare statements
 	/**
-	 * Returns all of the declare error and declare warning members of this type,
+	 * @return all of the declare error and declare warning members of this type,
 	 * including declare error/warning members inherited from super-types
 	 */
 	public DeclareErrorOrWarning[] getDeclareErrorOrWarnings();
 	
 	/**
-	 * Returns all of the declare parents members of this type, including
+	 * @return all of the declare parents members of this type, including
 	 * declare parent members inherited from super-types
 	 */
 	public DeclareParents[] getDeclareParents();
 	
 	/**
-	 * Return all of the declare soft members of this type, including declare
+	 * @return all of the declare soft members of this type, including declare
 	 * soft members inherited from super-types
 	 */
 	public DeclareSoft[] getDeclareSofts();
 
 	/**
-	 * Return all of the declare annotation members of this type, including declare
+	 * @return all of the declare annotation members of this type, including declare
 	 * annotation members inherited from super-types
 	 */
 	public DeclareAnnotation[] getDeclareAnnotations();
 	
 	/**
-	 * Return all of the declare precedence members of this type, including declare
+	 * @return all of the declare precedence members of this type, including declare
 	 * precedence members inherited from super-types
 	 */
 	public DeclarePrecedence[] getDeclarePrecedence();
@@ -315,65 +358,66 @@ public interface AjType<T> extends Type, AnnotatedElement {
 	// misc
 	
 	/**
-	 * Returns the elements of this enum class, or null if this type does not represent
+	 * @return the elements of this enum class, or null if this type does not represent
 	 * an enum type.
 	 */
     public T[] getEnumConstants();
 	
     /**
-     * Returns an array of TypeVariable objects that represent the type variables declared by
+     * @return an array of TypeVariable objects that represent the type variables declared by
      * this type (if any)
      */
 	public TypeVariable<Class<T>>[] getTypeParameters();
 
 	/**
-	 * True if this is an enum type
+	 * @return true if this is an enum type
 	 */
 	public boolean isEnum();
 
 	/**
-	 * True if the given object is assignment-compatible with an object of the type represented
+	 * @param o the object to check for assignment compatibility
+	 * @return true if the given object is assignment-compatible with an object of the type represented
 	 * by this AjType
 	 */
 	public boolean isInstance(Object o);
 
 	/**
-	 * True if this is an interface type
+	 * @return true if this is an interface type
 	 */
 	public boolean isInterface();
 
 	/**
-	 * Returns true if and only if the underlying type is a local class
+	 * @return true if and only if the underlying type is a local class
 	 */
 	public boolean isLocalClass();
 	
 	/**
-	 * Returns true if and only if the underlying type is a member class
+	 * @return true if and only if the underlying type is a member class
 	 */
 	public boolean isMemberClass();
 	
 	/**
-	 * Return true if this is an array type
+	 * @return true if this is an array type
 	 */
 	public boolean isArray();
 
 	/**
-	 * Return true if this object represents a primitive type
+	 * @return true if this object represents a primitive type
 	 */
 	public boolean isPrimitive();
 
 	/**
-	 * Return true if this is an aspect type
+	 * @return true if this is an aspect type
 	 */
 	public boolean isAspect();
 	
 	/**
-	 * Returns true if and only if the underlying type is a member aspect
+	 * @return true if and only if the underlying type is a member aspect
 	 */
 	public boolean isMemberAspect();
 
 	/**
-	 * Returns true if and only if the underlying type is a privileged aspect
+	 * @return true if and only if the underlying type is a privileged aspect
 	 */
 	public boolean isPrivileged();
 	
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/AjTypeSystem.java b/runtime/src/main/java/org/aspectj/lang/reflect/AjTypeSystem.java
index 6999dac19..6e525dc0b 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/AjTypeSystem.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/AjTypeSystem.java
@@ -21,7 +21,7 @@ import org.aspectj.internal.lang.reflect.AjTypeImpl;
 /**
  * This is the anchor for the AspectJ runtime type system. 
  * Typical usage to get the AjType representation of a given type
- * at runtime is to call <code>AjType<Foo> fooType = AjTypeSystem.getAjType(Foo.class);</code>
+ * at runtime is to call <code>AjType&lt;Foo&gt; fooType = AjTypeSystem.getAjType(Foo.class);</code>
  */
 public class AjTypeSystem {
 	
@@ -34,6 +34,9 @@ public class AjTypeSystem {
 		 * and other AspectJ type members. AjType is the recommended reflection API for
 		 * AspectJ programs as it offers everything that java.lang.reflect does, with 
 		 * AspectJ-awareness on top.
+		 * @param <T> the expected type associated with the returned AjType
+		 * @param fromClass the class for which to discover the AjType
+		 * @return the AjType corresponding to the input class
 		 */
 		public static <T> AjType<T> getAjType(Class<T> fromClass) {
 			WeakReference<AjType> weakRefToAjType =  ajTypes.get(fromClass);
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/DeclareAnnotation.java b/runtime/src/main/java/org/aspectj/lang/reflect/DeclareAnnotation.java
index faee5d495..1d7ba34a7 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/DeclareAnnotation.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/DeclareAnnotation.java
@@ -22,33 +22,33 @@ public interface DeclareAnnotation {
 	public enum Kind { Field, Method, Constructor, Type };
 	
 	/**
-	 * The aspect that declared this member.
+	 * @return the aspect that declared this member.
 	 */
 	AjType<?> getDeclaringType();
 	
 	/**
-	 * The target element kind
+	 * @return the target element kind
 	 */
 	Kind getKind();
 	
 	/**
-	 * The target signature pattern. Returns null if getKind() == Type 
+	 * @return the target signature pattern. Returns null if getKind() == Type 
 	 */
 	SignaturePattern getSignaturePattern();
 	
 	/**
-	 * The target type pattern. Returns null if getKind() != Type
+	 * @return the target type pattern. Returns null if getKind() != Type
 	 */
 	TypePattern getTypePattern();
 	
 	/**
-	 * The declared annotation. If the declared annotation does not have runtime retention,
+	 * @return the declared annotation. If the declared annotation does not have runtime retention,
 	 * this method returns null.
 	 */
 	Annotation getAnnotation();
 	
 	/**
-	 * Returns the text of the annotation as declared in this member. Available for
+	 * @return the text of the annotation as declared in this member. Available for
 	 * both runtime and class-file retention annotations
 	 */
 	String getAnnotationAsText();
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/DeclareErrorOrWarning.java b/runtime/src/main/java/org/aspectj/lang/reflect/DeclareErrorOrWarning.java
index a6a5abc53..1892e5035 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/DeclareErrorOrWarning.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/DeclareErrorOrWarning.java
@@ -18,22 +18,22 @@ package org.aspectj.lang.reflect;
 public interface DeclareErrorOrWarning {
 	
 	/**
-	 * The type that declared this declare warning or declare error member. 
+	 * @return the type that declared this declare warning or declare error member. 
 	 */
 	AjType getDeclaringType();
 	
 	/**
-	 * The pointcut expression associated with the warning or error
+	 * @return the pointcut expression associated with the warning or error
 	 */
 	PointcutExpression getPointcutExpression();
 	
 	/**
-	 * The message associated with the declare warning / declare error
+	 * @return the message associated with the declare warning / declare error
 	 */
 	String getMessage();
 	
 	/**
-	 * True if this is a declare error member, false if it is declare warning
+	 * @return true if this is a declare error member, false if it is declare warning
 	 */
 	boolean isError();
 	
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/DeclareParents.java b/runtime/src/main/java/org/aspectj/lang/reflect/DeclareParents.java
index 8d3c98b78..2800f5d6c 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/DeclareParents.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/DeclareParents.java
@@ -19,28 +19,29 @@ import java.lang.reflect.Type;
 public interface DeclareParents {
 
 	/**
-	 * The declaring aspect
+	 * @return the declaring aspect
 	 */
 	AjType getDeclaringType();
 	
 	/**
-	 * The target type pattern
+	 * @return the target type pattern
 	 */
 	TypePattern getTargetTypesPattern();
 	
 	/**
-	 * True if this is a declare parents...extends member declaration
+	 * @return true if this is a declare parents...extends member declaration
 	 */
 	boolean isExtends();
 	
 	/**
-	 * True if this is a declare parents...implements member declaration
+	 * @return true if this is a declare parents...implements member declaration
 	 */
 	boolean isImplements();
 	
 	/**
-	 * The set of types that the types matching getTargetTypesPattern are 
+	 * @return the set of types that the types matching getTargetTypesPattern are 
 	 * declared to implement or extend
+	 * @throws ClassNotFoundException if any types cannot be found
 	 */
 	Type[] getParentTypes() throws ClassNotFoundException;
 	
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/DeclarePrecedence.java b/runtime/src/main/java/org/aspectj/lang/reflect/DeclarePrecedence.java
index 894580b70..26b415ecf 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/DeclarePrecedence.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/DeclarePrecedence.java
@@ -18,12 +18,12 @@ package org.aspectj.lang.reflect;
 public interface DeclarePrecedence {
 
 	/**
-	 * The declaring aspect
+	 * @return the declaring aspect
 	 */
 	AjType getDeclaringType();
 	
 	/**
-	 * Returns an ordered set of type patterns. An aspect matching
+	 * @return an ordered set of type patterns. An aspect matching
 	 * a type pattern at a lower index in the array takes precedence
 	 * over an aspect that only matches a type pattern at a higher
 	 * index in the array.
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/DeclareSoft.java b/runtime/src/main/java/org/aspectj/lang/reflect/DeclareSoft.java
index cc607d680..55ade67f3 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/DeclareSoft.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/DeclareSoft.java
@@ -17,17 +17,18 @@ package org.aspectj.lang.reflect;
 public interface DeclareSoft {
 	
 	/**
-	 * The aspect that declared this member
+	 * @return the aspect that declared this member
 	 */
 	AjType getDeclaringType();
 	
 	/**
-	 * The softened exception type
+	 * @return the softened exception type
+	 * @throws ClassNotFoundException if exception type cannot be found
 	 */
 	AjType getSoftenedExceptionType() throws ClassNotFoundException;
 	
 	/**
-	 * The pointcut determining the join points at which the exception is to be softened.
+	 * @return the pointcut determining the join points at which the exception is to be softened.
 	 */
 	PointcutExpression getPointcutExpression();
 
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeConstructorDeclaration.java b/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeConstructorDeclaration.java
index 8db4505e3..c4bae0346 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeConstructorDeclaration.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeConstructorDeclaration.java
@@ -20,17 +20,17 @@ import java.lang.reflect.Type;
 public interface InterTypeConstructorDeclaration extends InterTypeDeclaration {
 
 	/**
-	 * The constructor parameters
+	 * @return the constructor parameters
 	 */
 	AjType<?>[] getParameterTypes();
 	
 	/**
-	 * The generic constructor parameters
+	 * @return the generic constructor parameters
 	 */
 	Type[] getGenericParameterTypes();
 	
 	/**
-	 * The declared exceptions thrown by this constructor
+	 * @return the declared exceptions thrown by this constructor
 	 */
 	AjType<?>[] getExceptionTypes();
 }
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeDeclaration.java b/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeDeclaration.java
index c00461011..5c2efc2c4 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeDeclaration.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeDeclaration.java
@@ -17,17 +17,18 @@ package org.aspectj.lang.reflect;
 public interface InterTypeDeclaration {
 
 	/**
-	 * The declaring aspect
+	 * @return the declaring aspect
 	 */
 	AjType<?> getDeclaringType();
 	
 	/**
-	 * The target type of this ITD
+	 * @return the target type of this ITD
+	 * @throws ClassNotFoundException if the type cannot be found
 	 */
 	AjType<?> getTargetType() throws ClassNotFoundException;
 	
 	/**
-	 * Member modifiers, can be interpreted using java.lang.reflect.Modifier
+	 * @return member modifiers, can be interpreted using java.lang.reflect.Modifier
 	 */
 	int getModifiers();
 }
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeFieldDeclaration.java b/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeFieldDeclaration.java
index 5a8acd76c..e396b7a6f 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeFieldDeclaration.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeFieldDeclaration.java
@@ -19,17 +19,17 @@ import java.lang.reflect.Type;
 public interface InterTypeFieldDeclaration extends InterTypeDeclaration {
 	
 	/**
-	 * The field name
+	 * @return the field name
 	 */
 	String getName();
 	
 	/**
-	 * The field type
+	 * @return the field type
 	 */
 	AjType<?> getType();
 	
 	/**
-	 * The generic field type
+	 * @return the generic field type
 	 */
 	Type getGenericType();
 
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeMethodDeclaration.java b/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeMethodDeclaration.java
index e570d8d2d..11e3f72a9 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeMethodDeclaration.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/InterTypeMethodDeclaration.java
@@ -21,37 +21,37 @@ import java.lang.reflect.TypeVariable;
 public interface InterTypeMethodDeclaration extends InterTypeDeclaration {
 
 	/**
-	 * The name of this method
+	 * @return the name of this method
 	 */
 	String getName();
 	
 	/**
-	 * The method return type
+	 * @return the method return type
 	 */
 	AjType<?> getReturnType();
 	
 	/**
-	 * The generic return type
+	 * @return the generic return type
 	 */
 	Type getGenericReturnType();
 	
 	/**
-	 * The method parameters
+	 * @return the method parameters
 	 */
 	AjType<?>[] getParameterTypes();
 	
 	/**
-	 * The generic method parameters
+	 * @return the generic method parameters
 	 */
 	Type[] getGenericParameterTypes();
 	
 	/**
-	 * The type variables declared by this method 
+	 * @return the type variables declared by this method 
 	 */
 	TypeVariable<Method>[] getTypeParameters();
 	
 	/**
-	 * The declared exceptions thrown by this method
+	 * @return the declared exceptions thrown by this method
 	 */
 	AjType<?>[] getExceptionTypes();
 }
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/NoSuchAdviceException.java b/runtime/src/main/java/org/aspectj/lang/reflect/NoSuchAdviceException.java
index 6b1ca8fa0..dc133d340 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/NoSuchAdviceException.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/NoSuchAdviceException.java
@@ -25,7 +25,7 @@ public class NoSuchAdviceException extends Exception {
 	}
 	
 	/**
-	 * The advice name that could not be found.
+	 * @return the advice name that could not be found.
 	 */
 	public String getName() {
 		return name;
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/NoSuchPointcutException.java b/runtime/src/main/java/org/aspectj/lang/reflect/NoSuchPointcutException.java
index 0274b74b4..6027711f1 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/NoSuchPointcutException.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/NoSuchPointcutException.java
@@ -25,7 +25,7 @@ public class NoSuchPointcutException extends Exception {
 	}
 	
 	/**
-	 * The name of the pointcut that could not be found.
+	 * @return the name of the pointcut that could not be found.
 	 */
 	public String getName() {
 		return name;
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/PerClause.java b/runtime/src/main/java/org/aspectj/lang/reflect/PerClause.java
index c16feda33..32be9628c 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/PerClause.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/PerClause.java
@@ -15,8 +15,9 @@ package org.aspectj.lang.reflect;
  * AspectJ runtime representation of the per-clause associated with an aspect.
  */
 public interface PerClause {
+
 	/**
-	 * The kind of per-clause (singleton, perthis, pertarget,...)
+	 * @return the kind of per-clause (singleton, perthis, pertarget,...)
 	 */
 	PerClauseKind getKind();
 
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/Pointcut.java b/runtime/src/main/java/org/aspectj/lang/reflect/Pointcut.java
index dfec7ccbd..72b3ee33c 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/Pointcut.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/Pointcut.java
@@ -17,35 +17,35 @@ package org.aspectj.lang.reflect;
 public interface Pointcut {
 	
 	/**
-	 * The declared name of the pointcut.
+	 * @return the declared name of the pointcut.
 	 */
 	String getName();
 	
 	/**
-	 * The modifiers associated with the pointcut declaration. 
+	 * @return the modifiers associated with the pointcut declaration. 
 	 * Use java.lang.reflect.Modifier to interpret the return value
 	 */
 	int getModifiers();
 	
 	/**
-	 * The pointcut parameter types.
+	 * @return the pointcut parameter types.
 	 */
 	AjType<?>[] getParameterTypes();
 	
 	/**
-	 * The pointcut parameter names. Returns an array of empty strings
+	 * @return the pointcut parameter names. Returns an array of empty strings
 	 * of length getParameterTypes().length if parameter names are not
 	 * available at runtime.
 	 */
 	String[] getParameterNames();
 	
 	/**
-	 * The type that declared this pointcut
+	 * @return the type that declared this pointcut
 	 */
 	AjType getDeclaringType();
 
 	/**
-	 * The pointcut expression associated with this pointcut.
+	 * @return the pointcut expression associated with this pointcut.
 	 */
 	PointcutExpression getPointcutExpression();
 
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/PointcutBasedPerClause.java b/runtime/src/main/java/org/aspectj/lang/reflect/PointcutBasedPerClause.java
index db040ea62..c622124d1 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/PointcutBasedPerClause.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/PointcutBasedPerClause.java
@@ -14,12 +14,11 @@ package org.aspectj.lang.reflect;
 /**
  * Representation of a pointcut based per-clause associated with an aspect
  * (perthis/target/cflow/cflowbelow)
- *
  */
 public interface PointcutBasedPerClause extends PerClause {
 
 	/**
-	 * Get the associated pointcut expression
+	 * @return the associated pointcut expression
 	 */
 	PointcutExpression getPointcutExpression();
 }
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/PointcutExpression.java b/runtime/src/main/java/org/aspectj/lang/reflect/PointcutExpression.java
index e229ba1f0..b7d60ef27 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/PointcutExpression.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/PointcutExpression.java
@@ -18,7 +18,7 @@ package org.aspectj.lang.reflect;
 public interface PointcutExpression {
 
 	/**
-	 * Returns a String representation of the pointcut expression 
+	 * @return a string representation of the pointcut expression 
 	 */
 	String asString();
 }
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/SignaturePattern.java b/runtime/src/main/java/org/aspectj/lang/reflect/SignaturePattern.java
index 99ba44dda..35177cee9 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/SignaturePattern.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/SignaturePattern.java
@@ -17,7 +17,7 @@ package org.aspectj.lang.reflect;
  */
 public interface SignaturePattern {
 
-	/** return a String representation of this pattern */
+	/** @return a string representation of this pattern */
 	String asString();
 	
 }
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/SourceLocation.java b/runtime/src/main/java/org/aspectj/lang/reflect/SourceLocation.java
index 52f1dd7a6..7ba567f5f 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/SourceLocation.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/SourceLocation.java
@@ -24,6 +24,7 @@ public interface SourceLocation {
     /**
      * @deprecated can not be implemented for bytecode weaving, may
      * be removed in 1.1gold.
+     * @return the column
      */
     int getColumn();
 }
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/TypePattern.java b/runtime/src/main/java/org/aspectj/lang/reflect/TypePattern.java
index f3b69b421..96a4b179e 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/TypePattern.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/TypePattern.java
@@ -12,11 +12,13 @@
 package org.aspectj.lang.reflect;
 
 /**
- * AspectJ runtime representation of a type pattern as used in member declarations
- * such as declare parents.
+ * AspectJ runtime representation of a type pattern as used in member
+ * declarations such as declare parents.
  */
 public interface TypePattern {
 
-	/** a string representation of the pattern */
+	/**
+	 * @return a string representation of the pattern
+	 */
 	String asString();
 }
diff --git a/runtime/src/main/java/org/aspectj/lang/reflect/TypePatternBasedPerClause.java b/runtime/src/main/java/org/aspectj/lang/reflect/TypePatternBasedPerClause.java
index 402b883b9..a8ea1f0ae 100644
--- a/runtime/src/main/java/org/aspectj/lang/reflect/TypePatternBasedPerClause.java
+++ b/runtime/src/main/java/org/aspectj/lang/reflect/TypePatternBasedPerClause.java
@@ -19,7 +19,7 @@ package org.aspectj.lang.reflect;
 public interface TypePatternBasedPerClause {
 
 	/**
-	 * Get the associated type pattern
+	 * @return the associated type pattern
 	 */
 	TypePattern getTypePattern();
 	
diff --git a/runtime/src/main/java/org/aspectj/runtime/internal/AroundClosure.java b/runtime/src/main/java/org/aspectj/runtime/internal/AroundClosure.java
index 91f7f923c..41c165149 100644
--- a/runtime/src/main/java/org/aspectj/runtime/internal/AroundClosure.java
+++ b/runtime/src/main/java/org/aspectj/runtime/internal/AroundClosure.java
@@ -46,14 +46,17 @@ public abstract class AroundClosure {
 	}
 
 	/**
-	 * This takes in the same arguments as are passed to the proceed
-	 * call in the around advice (with primitives coerced to Object types)
+	 * @param args the same arguments as passed to the proceed (with primitives coerced to Object types)
+	 * @return the result of the invocation with those arguments
+	 * @throws Throwable if underlying invoked code throws an exception
 	 */
     public abstract Object run(Object[] args) throws Throwable;
 
     /**
      * This method is called to implicitly associate the closure with the joinpoint
      * as required for @AJ aspect proceed()
+     *      
+     * @return the associated ProceedingJoinPoint
      */
     public ProceedingJoinPoint linkClosureAndJoinPoint() {
         //TODO is this cast safe ?
@@ -65,6 +68,9 @@ public abstract class AroundClosure {
     /**
      * This method is called to implicitly associate the closure with the joinpoint
      * as required for @AJ aspect proceed()
+     * 
+     * @param flags indicating whether this/target found at joinpoint and bound
+     * @return the associated ProceedingJoinPoint
      */
     public ProceedingJoinPoint linkClosureAndJoinPoint(int flags) {
         //TODO is this cast safe ?
diff --git a/runtime/src/main/java/org/aspectj/runtime/internal/Conversions.java b/runtime/src/main/java/org/aspectj/runtime/internal/Conversions.java
index f74e8d919..0632ae8f8 100644
--- a/runtime/src/main/java/org/aspectj/runtime/internal/Conversions.java
+++ b/runtime/src/main/java/org/aspectj/runtime/internal/Conversions.java
@@ -129,11 +129,9 @@ public final class Conversions {
 		}
 	}
 	
-	/** 
-	 * identity function for now.  This is not typed to "void" because we happen
-	 * to know that in Java, any void context (i.e., {@link ExprStmt})
-	 *  can also handle a return value.
-	 */
+	// identity function for now.  This is not typed to "void" because we happen
+	// to know that in Java, any void context (i.e., {@link ExprStmt})
+	// can also handle a return value.
 	public static Object voidValue(Object o) {
 		if (o == null) {
 			return o;
diff --git a/runtime/src/main/java/org/aspectj/runtime/reflect/Factory.java b/runtime/src/main/java/org/aspectj/runtime/reflect/Factory.java
index 759a1367b..e2f414bfa 100644
--- a/runtime/src/main/java/org/aspectj/runtime/reflect/Factory.java
+++ b/runtime/src/main/java/org/aspectj/runtime/reflect/Factory.java
@@ -89,29 +89,24 @@ public final class Factory {
 	}
 
 	
-	/**
-	 * Create a signature and build a JoinPoint in one step.  Prior to 1.6.10 this was done as a two step operation in the generated
-	 * code but merging these methods in the runtime library enables the generated code to be shorter.  Generating code that
-	 * uses this method requires the weaver to be invoked with <tt>-Xset:targetRuntime1_6_10=true</tt>.
-	 * 
-	 * @since 1.6.10
-	 */
+	//
+	// Create a signature and build a JoinPoint in one step.  Prior to 1.6.10 this was done as a two step operation in the generated
+	// code but merging these methods in the runtime library enables the generated code to be shorter.  Generating code that
+	// uses this method requires the weaver to be invoked with <tt>-Xset:targetRuntime1_6_10=true</tt>.
+	// @since 1.6.10
 	public JoinPoint.StaticPart makeSJP(String kind, String modifiers, String methodName, String declaringType, String paramTypes,
 			String paramNames, String exceptionTypes, String returnType, int l) {
 		Signature sig = this.makeMethodSig(modifiers, methodName, declaringType, paramTypes, paramNames, exceptionTypes, returnType);
 		return new JoinPointImpl.StaticPartImpl(count++, kind, sig, makeSourceLoc(l, -1));
 	}
 	
-	/**
-	 * Create a signature and build a JoinPoint in one step.  Prior to 1.6.10 this was done as a two step operation in the generated
-	 * code but merging these methods in the runtime library enables the generated code to be shorter.  Generating code that
-	 * uses this method requires the weaver to be invoked with <tt>-Xset:targetRuntime1_6_10=true</tt>.
-	 * <p>
-	 * This method differs from the previous one in that it includes no exceptionTypes parameter - it is an optimization for the
-	 * case where there are no exceptions.  The generated code won't build an empty string and will not pass it into here.
-	 * 
-	 * @since 1.6.10
-	 */
+	// Create a signature and build a JoinPoint in one step.  Prior to 1.6.10 this was done as a two step operation in the generated
+	// code but merging these methods in the runtime library enables the generated code to be shorter.  Generating code that
+	// uses this method requires the weaver to be invoked with <tt>-Xset:targetRuntime1_6_10=true</tt>.
+	// This method differs from the previous one in that it includes no exceptionTypes parameter - it is an optimization for the
+	// case where there are no exceptions.  The generated code won't build an empty string and will not pass it into here.
+	// 
+	// @since 1.6.10
 	public JoinPoint.StaticPart makeSJP(String kind, String modifiers, String methodName, String declaringType, String paramTypes,
 			String paramNames, String returnType, int l) {
 		Signature sig = this.makeMethodSig(modifiers, methodName, declaringType, paramTypes, paramNames, "", returnType);