resolve all javadoc warnings in this plug-in
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/ast/TypeDeclaration.java b/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/ast/TypeDeclaration.java
index 9063edd..8b17721 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/ast/TypeDeclaration.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/ast/TypeDeclaration.java
@@ -976,7 +976,7 @@
 					&& field.binding.isPublic())
 				{
 					SourceTypeBinding enclosingTeam = (SourceTypeBinding)this.binding.enclosingType();
-					enclosingTeam.addSyntheticMethod(field.binding, true, true, false/*superAccess*/);
+					enclosingTeam.addSyntheticMethod(field.binding, true, true, false/*superAccess*/); // FIXME: mixing flags, superAccess 3. arg, shouldn't it be false??
 					enclosingTeam.addSyntheticMethod(field.binding, false, true, false/*superAccess*/);
 				}
 			}
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/lookup/ClassScope.java b/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/lookup/ClassScope.java
index f8ec700..2b164d6 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/lookup/ClassScope.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/lookup/ClassScope.java
@@ -711,7 +711,7 @@
 
 //{ObjectTeams: build additional structural elements
 	/**
-	 * @param typeParamters all type parameters perhaps including type value parameters.
+	 * @param typeParameters all type parameters perhaps including type value parameters.
 	 * @return remaining unconsumed type parameters.
 	 */
 	private TypeParameter[] filterTypeValueVariables(TypeParameter[] typeParameters)
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/lookup/MethodBinding.java b/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/lookup/MethodBinding.java
index da2f175..a4c1c30 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/lookup/MethodBinding.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/jdt/internal/compiler/lookup/MethodBinding.java
@@ -757,7 +757,7 @@
 protected TypeBinding generalizedReturnType = null; // only set if return and parameters are temporarily retrenched.
 /**
  * Revert signature enhancement and return only those parameters defined in the source code.
- * @return
+ * @return a nonnull array of parameter types without the enhancing args
  */
 public TypeBinding[] getSourceParameters() {
 	TypeBinding[] allParameters = this.parameters;
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/ConstantPoolSimpleConverter.java b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/ConstantPoolSimpleConverter.java
index 041aaaa..c5eae67 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/ConstantPoolSimpleConverter.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/ConstantPoolSimpleConverter.java
@@ -40,8 +40,7 @@
 
 	/**
 	 * @param srcRole    where the byte code is read from
-	 * @param srcBytes   bytes to read from
-	 * @param srcOffset  offset into srcBytes
+	 * @param srcMethod  method being copied
 	 * @param destBytes  where to write to
 	 * @param dstClassFile ClassFile of the destination class
 	 */
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/InheritedRolesAttribute.java b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/InheritedRolesAttribute.java
index 388e469..292eeee 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/InheritedRolesAttribute.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/InheritedRolesAttribute.java
@@ -40,7 +40,7 @@
     private ReferenceBinding[] _roles;
 
     /**
-     * @param type the team whose roles should be stored.
+     * @param teamBinding the team whose roles should be stored.
      */
     public InheritedRolesAttribute(ReferenceBinding teamBinding) {
         super(IOTConstants.INHERITED_ROLES,
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/OTDynCallinBindingsAttribute.java b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/OTDynCallinBindingsAttribute.java
index 801003d..62a2308 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/OTDynCallinBindingsAttribute.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/OTDynCallinBindingsAttribute.java
@@ -124,10 +124,9 @@
 		}
 		
 
-	    /** Compute the name of the file containing the given callin mapping.
-	     *  Do consider packages but no projects or source folders.
-	     * @param decl
-	     * @return
+	    /** 
+	     * Compute the name of the file containing the given callin mapping.
+	     * Do consider packages but no projects or source folders.
 	     */
 	    private char[] getFileName(CallinMappingDeclaration decl) {
 			CompilationUnitDeclaration compilationUnit = decl.scope.referenceCompilationUnit();
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/RoleFilesAttribute.java b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/RoleFilesAttribute.java
index 9f77928..771d05d 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/RoleFilesAttribute.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/bytecode/RoleFilesAttribute.java
@@ -37,11 +37,6 @@
 
 	char[][] roleNames;
 
-	/**
-	 * @param name
-	 * @param count
-	 * @param elementSize
-	 */
 	public RoleFilesAttribute(char[][] names) {
 		super(IOTConstants.ROLE_FILES, names.length, 2);
 		this.roleNames = names;
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/lookup/AbstractOTReferenceBinding.java b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/lookup/AbstractOTReferenceBinding.java
index 39c16e2..7bf08fb 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/lookup/AbstractOTReferenceBinding.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/lookup/AbstractOTReferenceBinding.java
@@ -125,7 +125,7 @@
 	}
 	/**
 	 * @param cpInhSrcs use this set to filter out duplicates due to diamond copy inheritance.
-	 * @return
+	 * @return a nonnull map from qualified callin names to callin bindings.
 	 */
 	HashMap<String, CallinCalloutBinding> internalGetCallins(HashSet<CallinCalloutBinding> cpInhSrcs)
 	{
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/lookup/OTClassScope.java b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/lookup/OTClassScope.java
index 33915be..323e099 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/lookup/OTClassScope.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/lookup/OTClassScope.java
@@ -82,8 +82,8 @@
 	/**
 	 * This factory method is used for nested team types only.
 	 *
-	 * @param unitScope
-	 * @param otType
+	 * @param parent parent scope
+	 * @param otType type for which to create the new scope
 	 * @return a fresh OTClassScope
 	 */
 	public static OTClassScope createMemberOTClassScope(ClassScope parent, TypeDeclaration otType)
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/lookup/SyntheticRoleFieldAccess.java b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/lookup/SyntheticRoleFieldAccess.java
index e15db36..d16091e 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/lookup/SyntheticRoleFieldAccess.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/lookup/SyntheticRoleFieldAccess.java
@@ -20,6 +20,7 @@
  **********************************************************************/
 package org.eclipse.objectteams.otdt.internal.core.compiler.lookup;
 
+import org.eclipse.jdt.annotation.Nullable;
 import org.eclipse.jdt.core.compiler.CharOperation;
 import org.eclipse.jdt.internal.compiler.ast.Argument;
 import org.eclipse.jdt.internal.compiler.ast.FieldDeclaration;
@@ -348,9 +349,10 @@
 	 * @param enclosingTeam
 	 * @param targetField
 	 * @param isReadAccess
-	 * @return
+	 * @param externalizedReceiver whether the receiver of this field access is an externalized role
+	 * @return a synthetic field accessor method or null if not found
 	 */
-	public static SyntheticMethodBinding getAccessorFor(ReferenceBinding enclosingTeam,
+	public static @Nullable SyntheticMethodBinding getAccessorFor(ReferenceBinding enclosingTeam,
 													    FieldBinding targetField,
 													    boolean isReadAccess,
 													    boolean externalizedReceiver)
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/model/RoleModel.java b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/model/RoleModel.java
index 904ed87..d34f1fe 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/model/RoleModel.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/model/RoleModel.java
@@ -979,8 +979,6 @@
 
 	/**
 	 * Retrieve the known sub roles (including this) as determined by RoleHierarchyAnalyzer.analyze().
-	 *
-	 * @param subRoles
 	 */
 	public RoleModel[] getSubRoles() {
 		return this._subRoles;
@@ -1146,8 +1144,8 @@
 	}
 
 	/**
-	 * @param field
-	 * @param newField
+	 * @param srcField a synthetic field from tsuper
+	 * @param newField the synthetic new field copy 
 	 */
 	public void addSyntheticFieldMapping(FieldBinding srcField, FieldBinding newField) {
 		this._syntheticMap.put(srcField, newField);
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/smap/LineInfoCollector.java b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/smap/LineInfoCollector.java
index bb0564a..8a0b1d2f 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/smap/LineInfoCollector.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/smap/LineInfoCollector.java
@@ -47,9 +47,6 @@
 
     /**
      * Does the given output line (as used in byte code) already have a re-mapping?
-     *
-     * @param outputStartLinenumber
-     * @return
      */

     public boolean existsLineInfoFor(int outputStartLinenumber)

     {

diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/statemachine/transformer/StandardElementGenerator.java b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/statemachine/transformer/StandardElementGenerator.java
index 2f014ce..bc60037 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/statemachine/transformer/StandardElementGenerator.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/statemachine/transformer/StandardElementGenerator.java
@@ -20,6 +20,7 @@
  **********************************************************************/
 package org.eclipse.objectteams.otdt.internal.core.compiler.statemachine.transformer;
 
+import org.eclipse.jdt.annotation.Nullable;
 import org.eclipse.jdt.core.compiler.CharOperation;
 import org.eclipse.jdt.internal.compiler.ast.*;
 import org.eclipse.jdt.internal.compiler.classfmt.ClassFileConstants;
@@ -105,10 +106,10 @@
 	 * 		public org.objectteams.Team _OT$getTeam()
 	 * If roleType is an interface generate the abstract interface method.
 	 *
-	 * @param roleType
-	 * @return
+	 * @param roleType the role to operate on
+	 * @return the binding of the created method or null
 	 */
-	public static MethodBinding createGetTeamMethod(TypeDeclaration roleType)
+	public static @Nullable MethodBinding createGetTeamMethod(TypeDeclaration roleType)
 	{
 		MethodBinding existingMethod = TypeAnalyzer.findMethod(
 				roleType.initializerScope,
@@ -170,7 +171,7 @@
 	/**
 	 * Retreive (or create) a team level method used for casting an expression to a role.
 	 * After casting also check the containingInstance against the current team.
-	 * @param teamClass
+	 * @param teamModel
 	 * @param roleType
 	 * @param scope (used only for lookup of j.l.Object)
 	 * @param searchSuper  should super classes of teamClass be search, too?
@@ -469,8 +470,9 @@
 	}
 
 	/**
+	 * @param scope use this for resolving a newly generated team expression
 	 * @param roleType retrieve the anchor from this type.
-	 * @param pos faked source code position (encoded start and end).
+	 * @param gen represents faked source code position.
 	 * @return a new reference
 	 */
 	private static Expression createTeamAnchorReference(BlockScope scope, DependentTypeBinding roleType, AstGenerator gen) {
@@ -579,7 +581,6 @@
      * @param roleType  the type to hold the new _OT$base field
      * @param baseclass the type of the field
      * @param createBinding should a FieldBinding be created now?
-     * @return
      */
 	public static void checkCreateBaseField(TypeDeclaration roleType,
 										    ReferenceBinding baseclass,
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/AllNodesVisitor.java b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/AllNodesVisitor.java
index 7f4977f..7895cc1 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/AllNodesVisitor.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/AllNodesVisitor.java
@@ -278,18 +278,9 @@
 	public void endVisit(LongLiteral node, BlockScope scope) {
 		visitNode(node);
 	}
-	/**
-	 * @param annotation
-	 * @param scope
-	 * @since 3.1
-	 */
 	public void endVisit(MarkerAnnotation node, BlockScope scope) {
 		visitNode(node);
 	}
-	/**
-	 * @param pair
-	 * @param scope
-	 */
 	public void endVisit(MemberValuePair node, BlockScope scope) {
 		visitNode(node);
 	}
@@ -302,11 +293,6 @@
 	public void endVisit(StringLiteralConcatenation node, BlockScope scope) {
 		visitNode(node);
 	}
-	/**
-	 * @param annotation
-	 * @param scope
-	 * @since 3.1
-	 */
 	public void endVisit(NormalAnnotation node, BlockScope scope) {
 		visitNode(node);
 	}
@@ -382,11 +368,6 @@
 	public void endVisit(ReturnStatement node, BlockScope scope) {
 		visitNode(node);
 	}
-	/**
-	 * @param annotation
-	 * @param scope
-	 * @since 3.1
-	 */
 	public void endVisit(SingleMemberAnnotation node, BlockScope scope) {
 		visitNode(node);
 	}
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/AstClone.java b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/AstClone.java
index 0cb85f9..406aa4e 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/AstClone.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/AstClone.java
@@ -326,8 +326,6 @@
 
     /**
      * Copy all source locations from srcMethod to generated tgtMethod
-     * @param method
-     * @param newmethod
      */
     public static void copySrcLocation(
             AbstractMethodDeclaration srcMethod,
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/AstEdit.java b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/AstEdit.java
index a465945..354f67a 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/AstEdit.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/AstEdit.java
@@ -349,9 +349,6 @@
 	/**
 	 * Adds a TypeDeclaration to a CompilationUnitDeclaration and link back.
 	 * (no further processing besides array growing).
-     *
-	 * @param compilationUnitDeclaration
-	 * @param typeDeclaration
 	 */
 	public static void addTypeDeclaration(
             CompilationUnitDeclaration unitDeclaration,
diff --git a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/RoleFileHelper.java b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/RoleFileHelper.java
index 158f56f..dcab118 100644
--- a/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/RoleFileHelper.java
+++ b/org.eclipse.jdt.core/compiler/org/eclipse/objectteams/otdt/internal/core/compiler/util/RoleFileHelper.java
@@ -35,6 +35,7 @@
 import org.eclipse.objectteams.otdt.internal.core.compiler.control.Config;
 import org.eclipse.objectteams.otdt.internal.core.compiler.control.Dependencies;
 import org.eclipse.objectteams.otdt.internal.core.compiler.control.ITranslationStates;
+import org.eclipse.objectteams.otdt.internal.core.compiler.model.TeamModel;
 import org.eclipse.objectteams.otdt.internal.core.compiler.statemachine.copyinheritance.CopyInheritance;
 
 /**
@@ -61,7 +62,7 @@
  * <li>If eager loading misses a role file that is needed later,
  *     {@link SourceTypeBinding#findTypeInTeamPackage} may retrieve a role file via the team package.
  *     Roles found this way are remembered using {@link TeamModel#addKnownRoleFile} and try to
- *     catch up using {@link Dependencies.lateRolesCatchup} and {@link CopyInheritance#copyLateRole}.
+ *     catch up using {@link Dependencies#lateRolesCatchup} and {@link CopyInheritance#copyLateRole}.
  * </ul>
  *
  * @author stephan
diff --git a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTNode.java b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTNode.java
index 5fd10e5..0dde4ac 100644
--- a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTNode.java
+++ b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTNode.java
@@ -810,7 +810,7 @@
 	/**
 	 * Node type constant indicating a node of type
 	 * <code>BaseConstructorMessageSend</code>.
-	 * @see BaseConstructorMessageSend
+	 * @see BaseConstructorInvocation
 	 */
 	public static final int BASE_CONSTRUCTOR_INVOCATION = 90;
 
@@ -838,7 +838,7 @@
     /**
      * Node type constant indicating a node of type
      * <code>RoleTypeDelaration</code>.
-     * @see RoleTypeDelaration
+     * @see RoleTypeDeclaration
      */
     public static final int ROLE_TYPE_DECLARATION = 94;
 
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/internal/compiler/parser/TypeConverter.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/internal/compiler/parser/TypeConverter.java
index 8975865..212ac13 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/internal/compiler/parser/TypeConverter.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/internal/compiler/parser/TypeConverter.java
@@ -726,13 +726,7 @@
 		return result;
 	}
 
-//{ObjectTeams: OT Elements are handled uniformely in source/binary types:
-	/**
-	 * @param methodMapping
-	 * @param compilationResult
-	 * @return
-	 * @throws JavaModelException 
-	 */
+//{ObjectTeams: OT Elements are handled uniformly in source/binary types:
 	protected AbstractMethodMappingDeclaration convertCallout(
 			IMethodMapping methodMapping, CompilationResult compilationResult) throws JavaModelException
 	{
diff --git a/org.eclipse.jdt.core/model/org/eclipse/objectteams/otdt/internal/core/OTTypeMapping.java b/org.eclipse.jdt.core/model/org/eclipse/objectteams/otdt/internal/core/OTTypeMapping.java
index 14bf542..b896f6d 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/objectteams/otdt/internal/core/OTTypeMapping.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/objectteams/otdt/internal/core/OTTypeMapping.java
@@ -145,8 +145,6 @@
 
 	/**
 	 * Get type's parent (for use as a hash key).
-	 * @param type
-	 * @return
 	 */
 	private IJavaElement getParent(IType type) {
 		IJavaElement parent;