TARGET_321 - doc and javadoc changes for bug 148115

25 files changed, 78 insertions, 60 deletions

diff --git a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/AST.java b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/AST.java
index 4818c4e45e..ddb7002b2e 100644
--- a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/AST.java
+++ b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/AST.java
@@ -36,8 +36,8 @@ import org.eclipse.text.edits.TextEdit;
  * instance.
  * <p>
  * Abstract syntax trees may be hand constructed by clients, using the
- * <code>new<it>TYPE</it></code> factory methods to create new nodes, and the
- * various <code>set<it>CHILD</it></code> methods 
+ * <code>new<i>TYPE</i></code> factory methods to create new nodes, and the
+ * various <code>set<i>CHILD</i></code> methods 
  * (see {@link org.eclipse.jdt.core.dom.ASTNode ASTNode} and its subclasses)
  * to connect them together.
  * </p>
diff --git a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTMatcher.java b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTMatcher.java
index c7631d1504..c0e84e052a 100644
--- a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTMatcher.java
+++ b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTMatcher.java
@@ -21,8 +21,8 @@ import java.util.List;
  * <code>n1</code> and <code>n2</code> are the AST root nodes of the subtrees.
  * </p>
  * <p>
- * For each different concrete AST node type <it>T</it> there is a
- * <code>public boolean match(<it>T</it> node, Object other)</code> method
+ * For each different concrete AST node type <i>T</i> there is a
+ * <code>public boolean match(<i>T</i> node, Object other)</code> method
  * that matches the given node against another object (typically another
  * AST node, although this is not essential). The default implementations
  * provided by this class tests whether the other object is a node of the
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 d283b9cbd1..abb8cd359f 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
@@ -36,7 +36,7 @@ import java.util.Map;
  * Clients can navigate upwards, from child to parent, as well as downwards,
  * from parent to child. Newly created nodes are unparented. When an 
  * unparented node is set as a child of a node (using a 
- * <code>set<it>CHILD</it></code> method), its parent link is set automatically
+ * <code>set<i>CHILD</i></code> method), its parent link is set automatically
  * and the parent link of the former child is set to <code>null</code>.
  * For nodes with properties that include a list of children (for example,
  * <code>Block</code> whose <code>statements</code> property is a list
@@ -68,8 +68,8 @@ import java.util.Map;
  * </p>
  * <p>
  * Abstract syntax trees may be hand constructed by clients, using the
- * <code>new<it>TYPE</it></code> factory methods (see <code>AST</code>) to
- * create new nodes, and the various <code>set<it>CHILD</it></code> methods
+ * <code>new<i>TYPE</i></code> factory methods (see <code>AST</code>) to
+ * create new nodes, and the various <code>set<i>CHILD</i></code> methods
  * to connect them together.
  * </p>
  * <p>
diff --git a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTParser.java b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTParser.java
index 7433e2a5a3..ae6a74aafa 100644
--- a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTParser.java
+++ b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTParser.java
@@ -324,7 +324,7 @@ public class ASTParser {
 	/**
      * Requests an abridged abstract syntax tree. 
      * By default, complete ASTs are returned.
-     *
+     * <p>
      * When <code>true</code> the resulting AST does not have nodes for
      * the entire compilation unit. Rather, the AST is only fleshed out
      * for the node that include the given source position. This kind of limited
@@ -735,7 +735,7 @@ public class ASTParser {
 	 * Note also the following parser parameters are used, regardless of what
 	 * may have been specified:
 	 * <ul>
-	 * <li>The {@linkplain #setResolveBindings(boolean) binding resolution flag} is <code>true</code<</li>
+	 * <li>The {@linkplain #setResolveBindings(boolean) binding resolution flag} is <code>true</code></li>
 	 * <li>The {@linkplain #setKind(int) parser kind} is <code>K_COMPILATION_UNIT</code></li>
 	 * <li>The {@linkplain #setSourceRange(int,int) source range} is <code>(0, -1)</code></li>
 	 * <li>The {@linkplain #setFocalPosition(int) focal position} is not set</li>
diff --git a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTVisitor.java b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTVisitor.java
index 1c5ca4403b..c254322b27 100644
--- a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTVisitor.java
+++ b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTVisitor.java
@@ -14,10 +14,10 @@ package org.eclipse.jdt.core.dom;
 /**
  * A visitor for abstract syntax trees.
  * <p>
- * For each different concrete AST node type <it>T</it> there are
+ * For each different concrete AST node type <i>T</i> there are
  * a pair of methods:
  * <ul>
- * <li><code>public boolean visit(<it>T</it> node)</code> - Visits
+ * <li><code>public boolean visit(<i>T</i> node)</code> - Visits
  * the given node to perform some arbitrary operation. If <code>true</code>
  * is returned, the given node's child nodes will be visited next; however,
  * if <code>false</code> is returned, the given node's child nodes will 
@@ -25,7 +25,7 @@ package org.eclipse.jdt.core.dom;
  * nothing and returns <code>true</code> (with the exception of 
  * {@link #visit(Javadoc) ASTVisitor.visit(Javadoc)}).
  * Subclasses may reimplement this method as needed.</li>
- * <li><code>public void endVisit(<it>T</it> node)</code> - Visits
+ * <li><code>public void endVisit(<i>T</i> node)</code> - Visits
  * the given node to perform some arbitrary operation. When used in the
  * conventional way, this method is called after all of the given node's
  * children have been visited (or immediately, if <code>visit</code> returned
@@ -73,7 +73,7 @@ package org.eclipse.jdt.core.dom;
  * been visited from the ones that are still to be visited (the cursor
  * is between the elements, rather than on an element). The cursor moves from
  * the head to the tail of this list, advancing to the next position just
- * <it>before</it> <code>visit</code> if called for that child. After the child
+ * <i>before</i> <code>visit</code> if called for that child. After the child
  * subtree has been completely visited, the visit moves on the child 
  * immediately after the cursor. Removing a child while it is being visited
  * does not alter the course of the visit. But any children added at positions
diff --git a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ArrayCreation.java b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ArrayCreation.java
index a065c6d972..dba490af22 100644
--- a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ArrayCreation.java
+++ b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ArrayCreation.java
@@ -19,7 +19,7 @@ import java.util.List;
  * <pre>
  * ArrayCreation:
  *    <b>new</b> PrimitiveType <b>[</b> Expression <b>]</b> { <b>[</b> Expression <b>]</b> } { <b>[</b> <b>]</b> }
- *    <b>new</b> TypeName <b>[</b> Expression ]</b> { <b>[</b> Expression <b>]</b> } { <b>[</b> <b>]</b> }
+ *    <b>new</b> TypeName <b>[</b> Expression <b>]</b> { <b>[</b> Expression <b>]</b> } { <b>[</b> <b>]</b> }
  *    <b>new</b> PrimitiveType <b>[</b> <b>]</b> { <b>[</b> <b>]</b> } ArrayInitializer
  *    <b>new</b> TypeName <b>[</b> <b>]</b> { <b>[</b> <b>]</b> } ArrayInitializer
  * </pre>
@@ -37,7 +37,7 @@ import java.util.List;
  * ArrayCreation:
  *    <b>new</b> PrimitiveType <b>[</b> Expression <b>]</b> { <b>[</b> Expression <b>]</b> } { <b>[</b> <b>]</b> }
  *    <b>new</b> TypeName [ <b>&lt;</b> Type { <b>,</b> Type } <b>&gt;</b> ]
- *        <b>[</b> Expression ]</b> { <b>[</b> Expression <b>]</b> } { <b>[</b> <b>]</b> }
+ *        <b>[</b> Expression <b>]</b> { <b>[</b> Expression <b>]</b> } { <b>[</b> <b>]</b> }
  *    <b>new</b> PrimitiveType <b>[</b> <b>]</b> { <b>[</b> <b>]</b> } ArrayInitializer
  *    <b>new</b> TypeName [ <b>&lt;</b> Type { <b>,</b> Type } <b>&gt;</b> ]
  *        <b>[</b> <b>]</b> { <b>[</b> <b>]</b> } ArrayInitializer
diff --git a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/CompilationUnit.java b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/CompilationUnit.java
index a13b244ee7..3aa6b2812f 100644
--- a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/CompilationUnit.java
+++ b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/CompilationUnit.java
@@ -390,6 +390,7 @@ public class CompilationUnit extends ASTNode {
 	 * for comments of all kinds (line, block, and doc), arranged in order
 	 * of increasing source position. 
 	 * </p>
+	 * <p>
 	 * Note on comment parenting: The {@link ASTNode#getParent() getParent()}
 	 * of a doc comment associated with a body declaration is the body
 	 * declaration node; for these comment nodes
diff --git a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ITypeBinding.java b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ITypeBinding.java
index 75b22d9769..69ec8c5480 100644
--- a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ITypeBinding.java
+++ b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ITypeBinding.java
@@ -472,6 +472,7 @@ public interface ITypeBinding extends IBinding {
      * Note that per construction, it can only contain one class or array type, 
      * at most, and then it is located in first position.
      * </p>
+     * <p>
      * Also note that array type bound may only occur in the case of a capture
      * binding, e.g. <code>capture-of ? extends Object[]</code>
      * </p>
@@ -755,6 +756,7 @@ public interface ITypeBinding extends IBinding {
 	 * class <code>java.lang.String</code> and whose erasure is the type
 	 * binding for the generic type <code>java.util.Collection</code>.
 	 * </p>
+	 * <p>
 	 * Note that {@link #isGenericType()},
 	 * {@link #isParameterizedType()},
 	 * and {@link #isRawType()} are mutually exclusive.
@@ -877,7 +879,7 @@ public interface ITypeBinding extends IBinding {
 	 * For example, a AST type like 
 	 * <code>Collection&lt;? extends Object&gt;</code> typically resolves to a
 	 * parameterized type binding whose type argument is a wildcard type
-	 * with upper type bound <code>java.util.Object/code>.
+	 * with upper type bound <code>java.util.Object</code>.
 	 * </p>
 	 *
 	 * @return <code>true</code> if this object represents a wildcard type,
diff --git a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/rewrite/ASTRewrite.java b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/rewrite/ASTRewrite.java
index 025b08b02c..bc86dc7d61 100644
--- a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/rewrite/ASTRewrite.java
+++ b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/rewrite/ASTRewrite.java
@@ -369,9 +369,9 @@ public class ASTRewrite {
      * (not part of the original AST) or a placeholder node (for example, one
      * created by {@link #createCopyTarget(ASTNode)}
 	 * or {@link #createStringPlaceholder(String, int)}); or it must be
-	 * </code>null</code>, indicating that the child should be deleted.
+	 * <code>null</code>, indicating that the child should be deleted.
 	 * If the given property is a simple property, the value must be the new
-	 * value (primitive types must be boxed) or </code>null</code>.
+	 * value (primitive types must be boxed) or <code>null</code>.
      * The AST itself is not actually modified in any way; rather, the rewriter
      * just records a note that this node has been changed in the specified way.
 	 * 
diff --git a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/rewrite/ImportRewrite.java b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/rewrite/ImportRewrite.java
index 4eff8463e2..a860dfd523 100644
--- a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/rewrite/ImportRewrite.java
+++ b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/rewrite/ImportRewrite.java
@@ -60,6 +60,7 @@ public final class ImportRewrite {
 	 * unnecessary to add import statements for. 
 	 * 
 	 * </p>
+	 * <p>
 	 * This class can be implemented by clients.
 	 * </p>
 	 */
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/BindingKey.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/BindingKey.java
index 1c6ce37312..022e2c2de6 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/BindingKey.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/BindingKey.java
@@ -67,8 +67,13 @@ public final class BindingKey {
 	 * For example:
 	 * <pre>
 	 * <code>
-	 * createParameterizedTypeBindingKey("Ljava/util/Map<TK;TV;>;", new String[] {"Ljava/lang/String;", "Ljava/lang/Object;"}) -> "Ljava/util/Map<Ljava/lang/String;Ljava/lang/Object;>;"
-	 * createParameterizedTypeBindingKey("Ljava/util/List<TE;>;", new String[] {}) -> "Ljava/util/List<>;"
+	 * createParameterizedTypeBindingKey(
+	 *     "Ljava/util/Map&lt;TK;TV;&gt;;", 
+	 *     new String[] {"Ljava/lang/String;", "Ljava/lang/Object;"}) -&gt; 
+	 *       "Ljava/util/Map&lt;Ljava/lang/String;Ljava/lang/Object;&gt;;"
+	 * createParameterizedTypeBindingKey(
+	 *     "Ljava/util/List&lt;TE;&gt;;", new String[] {}) -&gt; 
+	 *       "Ljava/util/List&lt;&gt;;"
 	 * </code>
 	 * </pre>
 	 * </p>
@@ -121,8 +126,10 @@ public final class BindingKey {
 	 * For example:
 	 * <pre>
 	 * <code>
-	 * createTypeVariableBindingKey("T", "Ljava/util/List<TE;>;") -> "Ljava/util/List<TE;>;:TT;"
-	 * createTypeVariableBindingKey("SomeTypeVariable", "Lp/X;.foo()V") -> "Lp/X;.foo()V:TSomeTypeVariable;"
+	 * createTypeVariableBindingKey("T", "Ljava/util/List&lt;TE;&gt;;") -&gt; 
+	 *   "Ljava/util/List&lt;TE;&gt;;:TT;"
+	 * createTypeVariableBindingKey("SomeTypeVariable", "Lp/X;.foo()V") -&gt; 
+	 *   "Lp/X;.foo()V:TSomeTypeVariable;"
 	 * </code>
 	 * </pre>
 	 * </p>
@@ -150,9 +157,11 @@ public final class BindingKey {
 	 * For example:
 	 * <pre>
 	 * <code>
-	 * createWilcardTypeBindingKey(null, Signature.C_STAR) -> "*"
-	 * createWilcardTypeBindingKey("Ljava/util/List<TE;>;", Signature.C_SUPER) -> "-Ljava/util/List<TE;>;"
-	 * createWilcardTypeBindingKey("Ljava/util/ArrayList;", Signature.C_EXTENDS) -> "+Ljava/util/ArrayList;"
+	 * createWilcardTypeBindingKey(null, Signature.C_STAR) -&gt; "*"
+	 * createWilcardTypeBindingKey("Ljava/util/List&lt;TE;&gt;;",
+	 *    Signature.C_SUPER) -&gt; "-Ljava/util/List&lt;TE;&gt;;"
+	 * createWilcardTypeBindingKey("Ljava/util/ArrayList;", Signature.C_EXTENDS) -&gt;
+	 *    "+Ljava/util/ArrayList;"
 	 * </code>
 	 * </pre>
 	 * </p>
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/CompletionProposal.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/CompletionProposal.java
index f31840629f..185955a351 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/CompletionProposal.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/CompletionProposal.java
@@ -1571,7 +1571,7 @@ public final class CompletionProposal extends InternalCompletionProposal {
 	 * </p>
 	 * <p>
 	 * <b>Note that this is an expensive thing to compute, which may require
-	 * parsing Java source files, etc. Use sparingly.
+	 * parsing Java source files, etc. Use sparingly.</b>
 	 * </p>
 	 * 
 	 * @param monitor the progress monitor, or <code>null</code> if none
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IAccessRule.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IAccessRule.java
index 052a53a80d..ee952bb78b 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IAccessRule.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IAccessRule.java
@@ -99,7 +99,7 @@ public interface IAccessRule {
 	int getKind();
 	
 	/**
-	 * Returns whether a type matching this rule should be ignored iff a type with 
+	 * <p>Returns whether a type matching this rule should be ignored iff a type with 
 	 * the same qualified name can be found on a later classpath entry with a better 
 	 * accessibility.</p>
 	 * <p>E.g. if a type p.X matches a rule K_NON_ACCESSIBLE | IGNORE_IF_BETTER 
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IClassFile.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IClassFile.java
index bee327f6b4..1889c9d070 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IClassFile.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IClassFile.java
@@ -48,7 +48,7 @@ public interface IClassFile extends IJavaElement, IParent, IOpenable, ISourceRef
  * Once in working copy mode, changes to this working copy or its children are done in memory.
  * Only the new buffer is affected. 
  * </p>
- * </p>
+ * <p>
  * Using {@link ICompilationUnit#commitWorkingCopy(boolean, IProgressMonitor)} on the working copy
  * will throw a <code>JavaModelException</code> as a class file is implicetly read-only.
  * </p>
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IClasspathEntry.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IClasspathEntry.java
index ff375002a1..34ccb8440f 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IClasspathEntry.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IClasspathEntry.java
@@ -374,8 +374,8 @@ public interface IClasspathEntry {
 	 *		path to the corresponding project resource.</li>
 	 *  <li>A variable entry (<code>CPE_VARIABLE</code>) - the first segment of the path 
 	 *      is the name of a classpath variable. If this classpath variable
-	 *		is bound to the path <it>P</it>, the path of the corresponding classpath entry
-	 *		is computed by appending to <it>P</it> the segments of the returned
+	 *		is bound to the path <i>P</i>, the path of the corresponding classpath entry
+	 *		is computed by appending to <i>P</i> the segments of the returned
 	 *		path without the variable.</li>
 	 *  <li> A container entry (<code>CPE_CONTAINER</code>) - the path of the entry
 	 * 	is the name of the classpath container, which can be bound indirectly to a set of classpath 
@@ -431,7 +431,7 @@ public interface IClasspathEntry {
 	/**
 	 * This is a helper method, which returns the resolved classpath entry denoted 
 	 * by an entry (if it is a variable entry). It is obtained by resolving the variable 
-	 * reference in the first segment. Returns <node>null</code> if unable to resolve using 
+	 * reference in the first segment. Returns <code>null</code> if unable to resolve using 
 	 * the following algorithm:
 	 * <ul>
 	 * <li> if variable segment cannot be resolved, returns <code>null</code></li>
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/ICodeAssist.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/ICodeAssist.java
index ac02b07416..11410ddbfa 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/ICodeAssist.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/ICodeAssist.java
@@ -157,6 +157,7 @@ public interface ICodeAssist {
 	 * @return the Java elements corresponding to the given selected text
 	 *
 	 * @exception JavaModelException if code resolve could not be performed. Reasons include:
+	 * <ul>
 	 *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 	 *  <li> The range specified is not within this element's
 	 *      source range (INDEX_OUT_OF_BOUNDS)
@@ -186,6 +187,7 @@ public interface ICodeAssist {
 	 * @return the Java elements corresponding to the given selected text
 	 *
 	 * @exception JavaModelException if code resolve could not be performed. Reasons include:
+	 * <ul>
 	 *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 	 *  <li> The range specified is not within this element's
 	 *      source range (INDEX_OUT_OF_BOUNDS)
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IMethod.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IMethod.java
index f7084b8d97..1b0be8743b 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IMethod.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IMethod.java
@@ -213,7 +213,7 @@ boolean isConstructor() throws JavaModelException;
  * <li>its name is equal to <code>"main"</code></li>
  * <li>its return type is <code>void</code></li>
  * <li>it is <code>static</code> and <code>public</code></li>
- * <li>it defines one parameter whose type's simple name is </code>String[]</code></li>
+ * <li>it defines one parameter whose type's simple name is <code>String[]</code></li>
  * </ul>
  * 
  * @exception JavaModelException if this element does not exist or if an
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IProblemRequestor.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IProblemRequestor.java
index e1817b2a7f..7781fdc45a 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IProblemRequestor.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IProblemRequestor.java
@@ -43,7 +43,7 @@ public interface IProblemRequestor {
 
 	/**
 	 * Predicate allowing the problem requestor to signal whether or not it is currently
-	 * interested by problem reports. When answering <code>false</false>, problem will
+	 * interested by problem reports. When answering <code>false</code>, problem will
 	 * not be discovered any more until the next iteration.
 	 * 
 	 * This  predicate will be invoked once prior to each problem detection iteration.
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/ISourceReference.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/ISourceReference.java
index 6c9946a9b4..f005327bdf 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/ISourceReference.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/ISourceReference.java
@@ -16,7 +16,6 @@ package org.eclipse.jdt.core;
  * <code>IPackageDeclaration</code>, <code>IImportDeclaration</code>,
  * <code>IImportContainer</code>, <code>IType</code>, <code>IField</code>,
  * <code>IMethod</code>, and <code>IInitializer</code>.
- * </ul>
  * <p>
  * Note: For <code>IClassFile</code>, <code>IType</code> and other members
  * derived from a binary type, the implementation returns source iff the
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IType.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IType.java
index 1050a2f426..e5aa94a309 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IType.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IType.java
@@ -428,7 +428,7 @@ public interface IType extends IMember {
 	
 	/**
 	 * Returns this type's fully qualified name followed by its type parameters between angle brakets if it is a generic type.
-	 * For example, "p.X<T>", "java.util.Map<java.lang.String, p.X>"
+	 * For example, "p.X&lt;T&gt;", "java.util.Map&lt;java.lang.String, p.X&gt;"
 	 * 
 	 * @exception JavaModelException if this element does not exist or if an
 	 *      exception occurs while accessing its corresponding resource.
@@ -492,7 +492,7 @@ public interface IType extends IMember {
 	
 	/**
 	 * Returns the methods and constructors declared by this type.
-	 * For binary types, this may include the special <code>&lt;clinit&gt</code>; method 
+	 * For binary types, this may include the special <code>&lt;clinit&gt;</code>; method 
 	 * and synthetic methods.
 	 * If this is a source type, the results are listed in the order
 	 * in which they appear in the source, otherwise, the results are
@@ -580,7 +580,7 @@ public interface IType extends IMember {
 	/**
 	 * Returns the names of interfaces that this type implements or extends,
 	 * in the order in which they are listed in the source.
-	 * </p>
+	 * <p>
 	 * For classes, this gives the interfaces that this class implements.
 	 * For interfaces, this gives the interfaces that this interface extends.
 	 * An empty collection is returned if this type does not implement or
@@ -802,7 +802,7 @@ public interface IType extends IMember {
 	 * <li>IType#newSupertypeHierarchy(IProgressMonitor)</li>
 	 * <li>IType#newTypeHierarchy(IJavaProject, IProgressMonitor)</li>
 	 * <li>IType#newTypeHierarchy(IProgressMonitor)</li>
-	 * </u>
+	 * </ul>
 	 * 
 	 * @param input stream where hierarchy will be read
 	 * @param monitor the given progress monitor
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/ITypeHierarchy.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/ITypeHierarchy.java
index 66b430d159..51c9732041 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/ITypeHierarchy.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/ITypeHierarchy.java
@@ -291,7 +291,7 @@ void removeTypeHierarchyChangedListener(ITypeHierarchyChangedListener listener);
  * <li>IType#newSupertypeHierarchy(IProgressMonitor)</li>
  * <li>IType#newTypeHierarchy(IJavaProject, IProgressMonitor)</li>
  * <li>IType#newTypeHierarchy(IProgressMonitor)</li>
- * </u>
+ * </ul>
  * 
  * @param outputStream output stream where the hierarchy will be stored
  * @param monitor the given progress monitor
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/JavaConventions.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/JavaConventions.java
index aeb8435990..9a058bdee2 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/JavaConventions.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/JavaConventions.java
@@ -110,6 +110,7 @@ public final class JavaConventions {
 
 	/**
 	 * Validate the given compilation unit name.
+	 * <p>
 	 * A compilation unit name must obey the following rules:
 	 * <ul>
 	 * <li> it must not be null
@@ -157,6 +158,7 @@ public final class JavaConventions {
 
 	/**
 	 * Validate the given .class file name.
+	 * <p>
 	 * A .class file name must obey the following rules:
 	 * <ul>
 	 * <li> it must not be null
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/JavaCore.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/JavaCore.java
index 67c4b8bc71..0f183c546f 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/JavaCore.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/JavaCore.java
@@ -1541,7 +1541,7 @@ public final class JavaCore extends Plugin {
 
 	/**
 	 * Returns the path held in the given classpath variable.
-	 * Returns <node>null</code> if unable to bind.
+	 * Returns <code>null</code> if unable to bind.
 	 * <p>
 	 * Classpath variable values are persisted locally to the workspace, and 
 	 * are preserved from session to session.
@@ -2550,6 +2550,7 @@ public final class JavaCore extends Plugin {
 	 *     - option id:         "org.eclipse.jdt.core.codeComplete.camelCaseMatch"
 	 *     - possible values:   { "enabled", "disabled" }
 	 *     - default:           "enabled"
+	 * </pre>
 	 */
  	public static Hashtable getDefaultOptions(){
  		return JavaModelManager.getJavaModelManager().getDefaultOptions();
@@ -2644,7 +2645,7 @@ public final class JavaCore extends Plugin {
 	/**
 	 * This is a helper method, which returns the resolved classpath entry denoted 
 	 * by a given entry (if it is a variable entry). It is obtained by resolving the variable 
-	 * reference in the first segment. Returns <node>null</code> if unable to resolve using 
+	 * reference in the first segment. Returns <code>null</code> if unable to resolve using 
 	 * the following algorithm:
 	 * <ul>
 	 * <li> if variable segment cannot be resolved, returns <code>null</code></li>
@@ -2808,7 +2809,7 @@ public final class JavaCore extends Plugin {
 	 * Only compilation units in working copy mode are returned.
 	 * If the owner is <code>null</code>, primary working copies are returned.
 	 * 
-	 * @param owner the given working copy owner or <null> for primary working copy owner
+	 * @param owner the given working copy owner or <code>null</code> for primary working copy owner
 	 * @return the list of working copies for a given owner
 	 * @since 3.0
 	 */
@@ -3790,7 +3791,7 @@ public final class JavaCore extends Plugin {
 	 * <p>
 	 *	It is possible to register an automatic initializer (<code>ClasspathVariableInitializer</code>),
 	 * which will be invoked through the extension point "org.eclipse.jdt.core.classpathVariableInitializer".
-	 * After resolution, a classpath variable entry may either correspond to a project or a library entry. </li>	 
+	 * After resolution, a classpath variable entry may either correspond to a project or a library entry.
 	 * <p>
 	 * e.g. Here are some examples of variable path usage<ul>
 	 * <li> "JDTCORE" where variable <code>JDTCORE</code> is 
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/Signature.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/Signature.java
index 94c953ab9d..a7e2528cfa 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/Signature.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/Signature.java
@@ -32,10 +32,10 @@ import org.eclipse.jdt.internal.core.util.Util;
  * <p>
  * Generic types introduce to the Java language in J2SE 1.5 add three new
  * facets to signatures: type variables, parameterized types with type arguments,
- * and formal type parameters. <it>Rich</it> signatures containing these facets
+ * and formal type parameters. <i>Rich</i> signatures containing these facets
  * only occur when dealing with code that makes overt use of the new language
  * features. All other code, and certainly all Java code written or compiled
- * with J2SE 1.4 or earlier, involved only <it>simple</it> signatures.
+ * with J2SE 1.4 or earlier, involved only <i>simple</i> signatures.
  * </p>
  * <p>
  * Note that the "Q" and "!" formats are specific to Eclipse; the remainder
@@ -302,7 +302,7 @@ public final class Signature {
 
 	/**
 	 * Character constant indicating a capture of a wildcard type in a 
-	 * signature.Value is <code>'!'</code>.
+	 * signature. Value is <code>'!'</code>.
 	 * @since 3.1
 	 */
 	public static final char C_CAPTURE	= '!';
@@ -1599,9 +1599,9 @@ public static char[] getQualifier(char[] name) {
  * For example:
  * <pre>
  * <code>
- * getQualifier("java.lang.Object") -> "java.lang"
- * getQualifier("Outer.Inner") -> "Outer"
- * getQualifier("java.util.List<java.lang.String>") -> "java.util"
+ * getQualifier("java.lang.Object") -&gt; "java.lang"
+ * getQualifier("Outer.Inner") -&gt; "Outer"
+ * getQualifier("java.util.List&lt;java.lang.String&gt;") -&gt; "java.util"
  * </code>
  * </pre>
  * </p>
@@ -1842,10 +1842,10 @@ public static char[] getSimpleName(char[] name) {
  * For example:
  * <pre>
  * <code>
- * getSimpleName("java.lang.Object") -> "Object"
+ * getSimpleName("java.lang.Object") -&gt; "Object"
  * </code>
  * <code>
- * getSimpleName("java.util.Map<java.lang.String, java.lang.Object>") -> "Map<String,Object>"
+ * getSimpleName("java.util.Map&lt;java.lang.String, java.lang.Object&gt;") -&gt; "Map&lt;String,Object&gt;"
  * </code>
  * </pre>
  * </p>
@@ -2036,10 +2036,11 @@ public static char[][] getSimpleNames(char[] name) {
  * For example:
  * <pre>
  * <code>
- * getSimpleNames("java.lang.Object") -> {"java", "lang", "Object"}
- * getSimpleNames("Object") -> {"Object"}
- * getSimpleNames("") -> {}
- * getSimpleNames("java.util.List<java.lang.String>") -> {"java", "lang", "List<java.lang.String"}
+ * getSimpleNames("java.lang.Object") -&gt; {"java", "lang", "Object"}
+ * getSimpleNames("Object") -&gt; {"Object"}
+ * getSimpleNames("") -&gt; {}
+ * getSimpleNames("java.util.List&lt;java.lang.String&gt;") -&gt; 
+ *   {"java", "util", "List&lt;java.lang.String&gt;"}
  * </code>
  * </pre>
  *
@@ -2060,8 +2061,8 @@ public static String[] getSimpleNames(String name) {
  * For example (using equivalent string-based method):
  * <pre>
  * <code>
- * removeCapture("LTest<!+Ljava.lang.Throwable;>;")
- * will return: "LTest<+Ljava.lang.Throwable;>;"
+ * removeCapture("LTest&lt;!+Ljava.lang.Throwable;&gt;;")
+ * will return: "LTest&lt;+Ljava.lang.Throwable;&gt;;"
  * </code>
  * </pre>
  * </p>
@@ -2086,8 +2087,8 @@ public static char[] removeCapture(char[] methodOrTypeSignature) {
  * For example:
  * <pre>
  * <code>
- * removeCapture("LTest<!+Ljava.lang.Throwable;>;")
- * will return: "LTest<+Ljava.lang.Throwable;>;"
+ * removeCapture("LTest&lt;!+Ljava.lang.Throwable;&gt;;")
+ * will return: "LTest&lt;+Ljava.lang.Throwable;&gt;;"
  * </code>
  * </pre>
  * </p>
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/eval/IEvaluationContext.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/eval/IEvaluationContext.java
index 871cf036fc..1f44230a91 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/eval/IEvaluationContext.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/eval/IEvaluationContext.java
@@ -342,7 +342,7 @@ public interface IEvaluationContext {
 		throws JavaModelException;
 	/**
 	 * Evaluates the given global variable. During this operation, 
-	 * this context's package declaration, imports, and <it>all</it> its declared 
+	 * this context's package declaration, imports, and <i>all</i> its declared 
 	 * variables are verified. The given requestor's <code>acceptProblem</code>
 	 * method will be called for each problem that is detected.
 	 * <p>