From bd6867a836dcac5681c7bc262d9707a348f61f7c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=D0=90=D0=BB=D0=B5=D0=BA=D1=81=D0=B0=D0=BD=D0=B4=D1=8A?=
 =?UTF-8?q?=D1=80=20=D0=9A=D1=83=D1=80=D1=82=D0=B0=D0=BA=D0=BE=D0=B2?=
 <akurtakov@gmail.com>
Date: Thu, 7 Dec 2023 15:36:04 +0200
Subject: [PATCH] Javadoc format fixes

Contributes to
https://github.com/eclipse-platform/eclipse.platform.releng.aggregator/pull/1531
---
 .../jdt/core/compiler/CharOperation.java      |  2 ++
 .../eclipse/jdt/core/compiler/IProblem.java   |  2 +-
 .../dom/org/eclipse/jdt/core/dom/ASTNode.java |  2 ++
 .../eclipse/jdt/core/dom/ITypeBinding.java    |  2 +-
 .../eclipse/jdt/core/dom/InfixExpression.java |  2 +-
 .../eclipse/jdt/core/dom/RecordPattern.java   |  2 ++
 .../jdt/core/dom/rewrite/ImportRewrite.java   |  2 +-
 .../formatter/CodeFormatterApplication.java   |  1 -
 .../DefaultCodeFormatterConstants.java        | 34 +++++++++----------
 .../core/formatter/IndentManipulation.java    |  2 +-
 .../eclipse/jdt/core/CompletionProposal.java  |  2 +-
 .../model/org/eclipse/jdt/core/Flags.java     |  2 +-
 .../org/eclipse/jdt/core/ICodeAssist.java     | 20 ++++++-----
 .../eclipse/jdt/core/IJavaElementDelta.java   |  2 +-
 .../model/org/eclipse/jdt/core/IType.java     |  5 ++-
 .../model/org/eclipse/jdt/core/JavaCore.java  |  8 ++---
 .../model/org/eclipse/jdt/core/Signature.java | 22 +++++++++---
 .../eclipse/jdt/core/WorkingCopyOwner.java    |  3 +-
 .../jdt/core/eval/IEvaluationContext.java     |  6 ++--
 .../org/eclipse/jdt/core/jdom/IDOMMethod.java |  4 +--
 .../org/eclipse/jdt/core/jdom/IDOMType.java   |  4 +--
 21 files changed, 77 insertions(+), 52 deletions(-)

diff --git a/org.eclipse.jdt.core.compiler.batch/src/org/eclipse/jdt/core/compiler/CharOperation.java b/org.eclipse.jdt.core.compiler.batch/src/org/eclipse/jdt/core/compiler/CharOperation.java
index e6c0b79af2c..02df6a076a7 100644
--- a/org.eclipse.jdt.core.compiler.batch/src/org/eclipse/jdt/core/compiler/CharOperation.java
+++ b/org.eclipse.jdt.core.compiler.batch/src/org/eclipse/jdt/core/compiler/CharOperation.java
@@ -4047,11 +4047,13 @@ public static final char[][] splitOn(
  * For example:
  * <ol>
  * <li><pre>
+ * {@code
  *    divider = ','
  *    array = { 'A' , '<', 'B', ',', 'C', '>', ',', 'D' }
  *    start = 0
  *    end = 8
  *    result => { {  'A' , '<', 'B', ',', 'C', '>'}, { 'D' }}
+ * }
  * </pre>
  * </li>
  * </ol>
diff --git a/org.eclipse.jdt.core.compiler.batch/src/org/eclipse/jdt/core/compiler/IProblem.java b/org.eclipse.jdt.core.compiler.batch/src/org/eclipse/jdt/core/compiler/IProblem.java
index 003cdb30a64..ae314990aa0 100644
--- a/org.eclipse.jdt.core.compiler.batch/src/org/eclipse/jdt/core/compiler/IProblem.java
+++ b/org.eclipse.jdt.core.compiler.batch/src/org/eclipse/jdt/core/compiler/IProblem.java
@@ -353,7 +353,7 @@ public interface IProblem {
 	/**
 	 * Problem Categories
 	 * The high bits of a problem ID contains information about the category of a problem.
-	 * For example, (problemID & TypeRelated) != 0, indicates that this problem is type related.
+	 * For example, (problemID &amp; TypeRelated) != 0, indicates that this problem is type related.
 	 *
 	 * A problem category can help to implement custom problem filters. Indeed, when numerous problems
 	 * are listed, focusing on import related problems first might be relevant.
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 141585a5ce5..19d602d429b 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
@@ -1819,6 +1819,7 @@ public final ASTNode getParent() {
 	 * Returns the location of this node within its parent,
 	 * or <code>null</code> if this is a root node.
 	 * <pre>
+	 * {@code
 	 * ASTNode node = ...;
 	 * ASTNode parent = node.getParent();
 	 * StructuralPropertyDescriptor location = node.getLocationInParent();
@@ -1827,6 +1828,7 @@ public final ASTNode getParent() {
 	 *    assert parent.getStructuralProperty(location) == node;
 	 * if ((location != null) && location.isChildListProperty())
 	 *    assert ((List) parent.getStructuralProperty(location)).contains(node);
+	 * }
 	 * </pre>
 	 * <p>
 	 * Note that the relationship between an AST node and its parent node
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 cb2c430eb07..6ecff74f4f6 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
@@ -59,7 +59,7 @@ public interface ITypeBinding extends IBinding {
 	 *
 	 * @param dimension the given dimension
 	 * @return an array type binding
-	 * @throws IllegalArgumentException:<ul>
+	 * @throws IllegalArgumentException <ul>
 	 * <li>if the receiver represents the void type</li>
 	 * <li>if the resulting dimensions is lower than one or greater than 255</li>
 	 * </ul>
diff --git a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/InfixExpression.java b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/InfixExpression.java
index c32c1087798..89a2b9a4d2a 100644
--- a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/InfixExpression.java
+++ b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/InfixExpression.java
@@ -110,7 +110,7 @@ public String toString() {
 		public static final Operator GREATER = new Operator(">");//$NON-NLS-1$
 		/** Less than or equals "&lt;=" operator. */
 		public static final Operator LESS_EQUALS = new Operator("<=");//$NON-NLS-1$
-		/** Greater than or equals "&gt=;" operator. */
+		/** Greater than or equals "&gt;=" operator. */
 		public static final Operator GREATER_EQUALS = new Operator(">=");//$NON-NLS-1$
 		/** Equals "==" operator. */
 		public static final Operator EQUALS = new Operator("==");//$NON-NLS-1$
diff --git a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/RecordPattern.java b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/RecordPattern.java
index f46468bb25c..b1a1f9d2b1e 100644
--- a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/RecordPattern.java
+++ b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/RecordPattern.java
@@ -22,8 +22,10 @@
  * TypePattern pattern AST node type.
  *
  * <pre>
+ * {@code
  * RecordPattern:
  *      Pattern<Pattern<Patterns....>> Type SimpleName
+ * }
  * </pre>
  *
  * @since 3.31
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 ed2f9c46202..6a6066ec118 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
@@ -1399,7 +1399,7 @@ public String[] getCreatedImports() {
 	 * <p>
 	 * Note that this list doesn't need to be the same as the added static imports ({@link #getAddedStaticImports()}) as
 	 * implicit imports are not created and some imports are represented by on-demand imports instead.
-	 * </p
+	 * </p>
 	 * @return the created imports
 	 */
 	public String[] getCreatedStaticImports() {
diff --git a/org.eclipse.jdt.core/formatter/org/eclipse/jdt/core/formatter/CodeFormatterApplication.java b/org.eclipse.jdt.core/formatter/org/eclipse/jdt/core/formatter/CodeFormatterApplication.java
index 3ed4fdab4d7..d7ed437e28f 100644
--- a/org.eclipse.jdt.core/formatter/org/eclipse/jdt/core/formatter/CodeFormatterApplication.java
+++ b/org.eclipse.jdt.core/formatter/org/eclipse/jdt/core/formatter/CodeFormatterApplication.java
@@ -48,7 +48,6 @@
  * files first so that a file does not get formatted twice. 2. Use a text based
  * progress monitor for output.</p>
  *
- * @author Ben Konrath <bkonrath@redhat.com>
  * @since 3.2
  * @noinstantiate This class is not intended to be instantiated by clients.
  * @noextend This class is not intended to be subclassed by clients.
diff --git a/org.eclipse.jdt.core/formatter/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.java b/org.eclipse.jdt.core/formatter/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.java
index f5ae7e982e5..96160712c94 100644
--- a/org.eclipse.jdt.core/formatter/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.java
+++ b/org.eclipse.jdt.core/formatter/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.java
@@ -303,7 +303,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_ALIGNMENT_FOR_ARGUMENTS_IN_QUALIFIED_ALLOCATION_EXPRESSION = JavaCore.PLUGIN_ID + ".formatter.alignment_for_arguments_in_qualified_allocation_expression";	 //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option for alignment of assignment (=, +=, -=, *=, /=, %=, &=, ^=, |=, <<=, >>=, >>>=)
+	 * FORMATTER / Option for alignment of assignment {@code (=, +=, -=, *=, /=, %=, &=, ^=, |=, <<=, >>=, >>>=) }
 	 *     - option id:         "org.eclipse.jdt.core.formatter.alignment_for_assignment"
 	 *     - possible values:   values returned by <code>createAlignmentValue(boolean, int, int)</code> call
 	 *     - default:           createAlignmentValue(false, WRAP_NO_SPLIT, INDENT_DEFAULT)
@@ -358,7 +358,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_ALIGNMENT_FOR_STRING_CONCATENATION = JavaCore.PLUGIN_ID + ".formatter.alignment_for_string_concatenation";	 //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option for alignment of expressions with shift operators (<<, >>, >>>)
+	 * FORMATTER / Option for alignment of expressions with shift operators {@code (<<, >>, >>>) }
 	 *     - option id:         "org.eclipse.jdt.core.formatter.alignment_for_shift_operator"
 	 *     - possible values:   values returned by <code>createAlignmentValue(boolean, int, int)</code> call
 	 *     - default:           createAlignmentValue(false, WRAP_COMPACT, INDENT_DEFAULT)
@@ -369,7 +369,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_ALIGNMENT_FOR_SHIFT_OPERATOR = JavaCore.PLUGIN_ID + ".formatter.alignment_for_shift_operator";	 //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option for alignment of expressions with relational operators (<, >, <=, >=, ==, !=)
+	 * FORMATTER / Option for alignment of expressions with relational operators {@code (<, >, <=, >=, ==, !=)}
 	 *     - option id:         "org.eclipse.jdt.core.formatter.alignment_for_relational_operator"
 	 *     - possible values:   values returned by <code>createAlignmentValue(boolean, int, int)</code> call
 	 *     - default:           createAlignmentValue(false, WRAP_COMPACT, INDENT_DEFAULT)
@@ -380,7 +380,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_ALIGNMENT_FOR_RELATIONAL_OPERATOR = JavaCore.PLUGIN_ID + ".formatter.alignment_for_relational_operator";	 //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option for alignment of expressions with bitwise operators (&, ^, |)
+	 * FORMATTER / Option for alignment of expressions with bitwise operators (&amp;, ^, |)
 	 *     - option id:         "org.eclipse.jdt.core.formatter.alignment_for_bitwise_operator"
 	 *     - possible values:   values returned by <code>createAlignmentValue(boolean, int, int)</code> call
 	 *     - default:           createAlignmentValue(false, WRAP_COMPACT, INDENT_DEFAULT)
@@ -391,7 +391,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_ALIGNMENT_FOR_BITWISE_OPERATOR = JavaCore.PLUGIN_ID + ".formatter.alignment_for_bitwise_operator";	 //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option for alignment of expressions with logical operators (&&, ||)
+	 * FORMATTER / Option for alignment of expressions with logical operators (&amp;&amp;, ||)
 	 *     - option id:         "org.eclipse.jdt.core.formatter.alignment_for_logical_operator"
 	 *     - possible values:   values returned by <code>createAlignmentValue(boolean, int, int)</code> call
 	 *     - default:           createAlignmentValue(false, WRAP_COMPACT, INDENT_DEFAULT)
@@ -2647,7 +2647,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_INSERT_SPACE_AFTER_STRING_CONCATENATION = JavaCore.PLUGIN_ID + ".formatter.insert_space_after_string_concatenation"; //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option to insert a space after a shift operator (<<, >>, >>>)
+	 * FORMATTER / Option to insert a space after a shift operator {@code (<<, >>, >>>)}
 	 *     - option id:         "org.eclipse.jdt.core.formatter.insert_space_after_shift_operator"
 	 *     - possible values:   { INSERT, DO_NOT_INSERT }
 	 *     - default:           INSERT
@@ -2659,7 +2659,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_INSERT_SPACE_AFTER_SHIFT_OPERATOR = JavaCore.PLUGIN_ID + ".formatter.insert_space_after_shift_operator"; //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option to insert a space after a relational operator (<, >, <=, >=, ==, !=)
+	 * FORMATTER / Option to insert a space after a relational operator {@code (<, >, <=, >=, ==, !=)}
 	 *     - option id:         "org.eclipse.jdt.core.formatter.insert_space_after_relational_operator"
 	 *     - possible values:   { INSERT, DO_NOT_INSERT }
 	 *     - default:           INSERT
@@ -2671,7 +2671,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_INSERT_SPACE_AFTER_RELATIONAL_OPERATOR = JavaCore.PLUGIN_ID + ".formatter.insert_space_after_relational_operator"; //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option to insert a space after a bitwise operator (&, ^, |)
+	 * FORMATTER / Option to insert a space after a bitwise operator (&amp;, ^, |)
 	 *     - option id:         "org.eclipse.jdt.core.formatter.insert_space_after_bitwise_operator"
 	 *     - possible values:   { INSERT, DO_NOT_INSERT }
 	 *     - default:           INSERT
@@ -2683,7 +2683,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_INSERT_SPACE_AFTER_BITWISE_OPERATOR = JavaCore.PLUGIN_ID + ".formatter.insert_space_after_bitwise_operator"; //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option to insert a space after a logical operator (&&, ||)
+	 * FORMATTER / Option to insert a space after a logical operator (&amp;&amp;, ||)
 	 *     - option id:         "org.eclipse.jdt.core.formatter.insert_space_after_logical_operator"
 	 *     - possible values:   { INSERT, DO_NOT_INSERT }
 	 *     - default:           INSERT
@@ -3552,7 +3552,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_INSERT_SPACE_BEFORE_STRING_CONCATENATION = JavaCore.PLUGIN_ID + ".formatter.insert_space_before_string_concatenation"; //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option to insert a space before a shift operator (<<, >>, >>>)
+	 * FORMATTER / Option to insert a space before a shift operator {@code (<<, >>, >>>)}
 	 *     - option id:         "org.eclipse.jdt.core.formatter.insert_space_before_shift_operator"
 	 *     - possible values:   { INSERT, DO_NOT_INSERT }
 	 *     - default:           INSERT
@@ -3564,7 +3564,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_INSERT_SPACE_BEFORE_SHIFT_OPERATOR = JavaCore.PLUGIN_ID + ".formatter.insert_space_before_shift_operator"; //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option to insert a space before a relational operator (<, >, <=, >=, ==, !=)
+	 * FORMATTER / Option to insert a space before a relational operator {@code (<, >, <=, >=, ==, !=)}
 	 *     - option id:         "org.eclipse.jdt.core.formatter.insert_space_before_relational_operator"
 	 *     - possible values:   { INSERT, DO_NOT_INSERT }
 	 *     - default:           INSERT
@@ -3576,7 +3576,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_INSERT_SPACE_BEFORE_RELATIONAL_OPERATOR = JavaCore.PLUGIN_ID + ".formatter.insert_space_before_relational_operator"; //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option to insert a space before a bitwise operator (&, ^, |)
+	 * FORMATTER / Option to insert a space before a bitwise operator (&amp;, ^, |)
 	 *     - option id:         "org.eclipse.jdt.core.formatter.insert_space_before_bitwise_operator"
 	 *     - possible values:   { INSERT, DO_NOT_INSERT }
 	 *     - default:           INSERT
@@ -3588,7 +3588,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_INSERT_SPACE_BEFORE_BITWISE_OPERATOR = JavaCore.PLUGIN_ID + ".formatter.insert_space_before_bitwise_operator"; //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option to insert a space before a logical operator (&&, ||)
+	 * FORMATTER / Option to insert a space before a logical operator (&amp;&amp;, ||)
 	 *     - option id:         "org.eclipse.jdt.core.formatter.insert_space_before_logical_operator"
 	 *     - possible values:   { INSERT, DO_NOT_INSERT }
 	 *     - default:           INSERT
@@ -5374,7 +5374,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_WRAP_BEFORE_STRING_CONCATENATION = JavaCore.PLUGIN_ID + ".formatter.wrap_before_string_concatenation"; //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option to wrap before the shift operator (<<, >>, >>>)
+	 * FORMATTER / Option to wrap before the shift operator {@code (<<, >>, >>>)}
 	 *     - option id:         "org.eclipse.jdt.core.formatter.wrap_before_shift_operator"
 	 *     - possible values:   { TRUE, FALSE }
 	 *     - default:           TRUE
@@ -5387,7 +5387,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_WRAP_BEFORE_SHIFT_OPERATOR = JavaCore.PLUGIN_ID + ".formatter.wrap_before_shift_operator"; //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option to wrap before the relational operator (<, >, <=, >=, ==, !=)
+	 * FORMATTER / Option to wrap before the relational operator {@code (<, >, <=, >=, ==, !=)}
 	 *     - option id:         "org.eclipse.jdt.core.formatter.wrap_before_"
 	 *     - possible values:   { TRUE, FALSE }
 	 *     - default:           TRUE
@@ -5400,7 +5400,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_WRAP_BEFORE_RELATIONAL_OPERATOR = JavaCore.PLUGIN_ID + ".formatter.wrap_before_relational_operator"; //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option to wrap before the bitwise operator (&, ^, |)
+	 * FORMATTER / Option to wrap before the bitwise operator (&amp;, ^, |)
 	 *     - option id:         "org.eclipse.jdt.core.formatter.wrap_before_bitwise_operator"
 	 *     - possible values:   { TRUE, FALSE }
 	 *     - default:           TRUE
@@ -5413,7 +5413,7 @@ public class DefaultCodeFormatterConstants {
 	public static final String FORMATTER_WRAP_BEFORE_BITWISE_OPERATOR = JavaCore.PLUGIN_ID + ".formatter.wrap_before_bitwise_operator"; //$NON-NLS-1$
 	/**
 	 * <pre>
-	 * FORMATTER / Option to wrap before the logical operator (&&, ||)
+	 * FORMATTER / Option to wrap before the logical operator (&amp;&amp;, ||)
 	 *     - option id:         "org.eclipse.jdt.core.formatter.wrap_before_logical_operator"
 	 *     - possible values:   { TRUE, FALSE }
 	 *     - default:           TRUE
diff --git a/org.eclipse.jdt.core/formatter/org/eclipse/jdt/core/formatter/IndentManipulation.java b/org.eclipse.jdt.core/formatter/org/eclipse/jdt/core/formatter/IndentManipulation.java
index f41aeb74151..18b83243b12 100644
--- a/org.eclipse.jdt.core/formatter/org/eclipse/jdt/core/formatter/IndentManipulation.java
+++ b/org.eclipse.jdt.core/formatter/org/eclipse/jdt/core/formatter/IndentManipulation.java
@@ -182,7 +182,7 @@ public static String extractIndentString(String line, int tabWidth, int indentWi
 	/**
 	 * Removes the given number of indentation units from a given line. If the line
 	 * has less indent than the given indentUnitsToRemove, all the available indentation is removed.
-	 * If <code>indentsToRemove <= 0 or indent == 0</code> the line is returned.
+	 * If <code>indentsToRemove &lt;= 0 or indent == 0</code> the line is returned.
 	 *
 	 * @param line the line to trim
 	 * @param tabWidth the width of one tab in space equivalents
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 cd1c4b40b96..28c1497777e 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
@@ -1800,7 +1800,7 @@ public void setReceiverRange(int startIndex, int endIndex) {
 	}
 
 	/**
-	 * Returns whether it is safe to use the '<>' (diamond) operator in place of explicitly specifying
+	 * Returns whether it is safe to use the {@code '<>'} (diamond) operator in place of explicitly specifying
 	 * type arguments for this proposal.
 	 *
 	 * <p>
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/Flags.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/Flags.java
index 3f0be8e5f27..5bcade105d0 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/Flags.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/Flags.java
@@ -511,7 +511,7 @@ public static boolean isModule(int flags) {
 	 * unexpected description. Clients should ensure that the AccVarargs is not included in the flags of a method as follows:
 	 * <pre>
 	 * IMethod method = ...
-	 * int flags = method.getFlags() & ~Flags.AccVarargs;
+	 * int flags = method.getFlags() &amp; ~Flags.AccVarargs;
 	 * return Flags.toString(flags);
 	 * </pre>
 	 * <p>
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 17b354736f8..c154fa020c0 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
@@ -35,7 +35,7 @@ public interface ICodeAssist {
 	 *
 	 * @exception JavaModelException if code assist could not be performed. Reasons include:<ul>
 	 *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
-	 *  <li> The position specified is < -1 or is greater than this compilation unit's
+	 *  <li> The position specified is &lt; -1 or is greater than this compilation unit's
 	 *      source length (INDEX_OUT_OF_BOUNDS)
 	 * </ul>
 	 *
@@ -55,7 +55,7 @@ void codeComplete(int offset, ICodeCompletionRequestor requestor)
 	 * @param requestor the given completion requestor
 	 * @exception JavaModelException if code assist could not be performed. Reasons include:<ul>
 	 *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
-	 *  <li> The position specified is < -1 or is greater than this compilation unit's
+	 *  <li> The position specified is &lt; -1 or is greater than this compilation unit's
 	 *      source length (INDEX_OUT_OF_BOUNDS)
 	 * </ul>
 	 *
@@ -77,7 +77,7 @@ void codeComplete(int offset, ICompletionRequestor requestor)
 	 * @param requestor the given completion requestor
 	 * @exception JavaModelException if code assist could not be performed. Reasons include:<ul>
 	 *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
-	 *  <li> The position specified is < -1 or is greater than this compilation unit's
+	 *  <li> The position specified is &lt; -1 or is greater than this compilation unit's
 	 *      source length (INDEX_OUT_OF_BOUNDS)
 	 * </ul>
 	 *
@@ -100,7 +100,7 @@ void codeComplete(int offset, CompletionRequestor requestor)
 	 * assist operation when a specified amount of time is reached could be used.
 	 * </p>
 	 *
-	 * <pre>
+	 * <pre>{@code
 	 * new IProgressMonitor() {
 	 *     private final static int TIMEOUT = 500; //ms
 	 *     private long endTime;
@@ -112,6 +112,7 @@ void codeComplete(int offset, CompletionRequestor requestor)
 	 *     }
 	 *     ...
 	 * };
+	 * }
 	 * </pre>
 	 *
 	 * @param offset the given offset position
@@ -119,7 +120,7 @@ void codeComplete(int offset, CompletionRequestor requestor)
 	 * @param monitor the progress monitor used to report progress
 	 * @exception JavaModelException if code assist could not be performed. Reasons include:<ul>
 	 *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
-	 *  <li> The position specified is < -1 or is greater than this compilation unit's
+	 *  <li> The position specified is &lt; -1 or is greater than this compilation unit's
 	 *      source length (INDEX_OUT_OF_BOUNDS)
 	 * </ul>
 	 *
@@ -148,7 +149,7 @@ void codeComplete(int offset, CompletionRequestor requestor, IProgressMonitor mo
 	 * @param owner the owner of working copies that take precedence over their original compilation units
 	 * @exception JavaModelException if code assist could not be performed. Reasons include:<ul>
 	 *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
-	 *  <li> The position specified is < -1 or is greater than this compilation unit's
+	 *  <li> The position specified is &lt; -1 or is greater than this compilation unit's
 	 *      source length (INDEX_OUT_OF_BOUNDS)
 	 * </ul>
 	 *
@@ -178,7 +179,7 @@ void codeComplete(int offset, ICompletionRequestor requestor, WorkingCopyOwner o
 	 * @param owner the owner of working copies that take precedence over their original compilation units
 	 * @exception JavaModelException if code assist could not be performed. Reasons include:<ul>
 	 *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
-	 *  <li> The position specified is < -1 or is greater than this compilation unit's
+	 *  <li> The position specified is &lt; -1 or is greater than this compilation unit's
 	 *      source length (INDEX_OUT_OF_BOUNDS)
 	 * </ul>
 	 *
@@ -208,7 +209,7 @@ void codeComplete(int offset, CompletionRequestor requestor, WorkingCopyOwner ow
 	 * assist operation when a specified amount of time is reached could be used.
 	 * </p>
 	 *
-	 * <pre>
+	 * <pre>{@code
 	 * new IProgressMonitor() {
 	 *     private final static int TIMEOUT = 500; //ms
 	 *     private long endTime;
@@ -220,6 +221,7 @@ void codeComplete(int offset, CompletionRequestor requestor, WorkingCopyOwner ow
 	 *     }
 	 *     ...
 	 * };
+	 * }
 	 * </pre>
 	 *
 	 * @param offset the given offset position
@@ -228,7 +230,7 @@ void codeComplete(int offset, CompletionRequestor requestor, WorkingCopyOwner ow
 	 * @param monitor the progress monitor used to report progress
 	 * @exception JavaModelException if code assist could not be performed. Reasons include:<ul>
 	 *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
-	 *  <li> The position specified is < -1 or is greater than this compilation unit's
+	 *  <li> The position specified is &lt; -1 or is greater than this compilation unit's
 	 *      source length (INDEX_OUT_OF_BOUNDS)
 	 * </ul>
 	 *
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IJavaElementDelta.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IJavaElementDelta.java
index 9c9edb3b506..8e1f30ecc0b 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IJavaElementDelta.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/IJavaElementDelta.java
@@ -378,7 +378,7 @@ public interface IJavaElementDelta {
 	 * Returns flags that describe how an element has changed.
 	 * Such flags should be tested using the <code>&amp;</code> operand. For example:
 	 * <pre>
-	 * if ((delta.getFlags() & IJavaElementDelta.F_CONTENT) != 0) {
+	 * if ((delta.getFlags() &amp; IJavaElementDelta.F_CONTENT) != 0) {
 	 * 	// the delta indicates a content change
 	 * }
 	 * </pre>
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 3e2aa59fbf0..3f96c87312d 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
@@ -181,6 +181,7 @@ void codeComplete(
 	 * </p>
 	 *
 	 * <pre>
+	 * {@code
 	 * new IProgressMonitor() {
 	 *     private final static int TIMEOUT = 500; //ms
 	 *     private long endTime;
@@ -192,6 +193,7 @@ void codeComplete(
 	 *     }
 	 *     ...
 	 * };
+	 * }
 	 * </pre>
 	 *
 	 * @param snippet the code snippet
@@ -290,7 +292,7 @@ void codeComplete(
 	 * assist operation when a specified amount of time is reached could be used.
 	 * </p>
 	 *
-	 * <pre>
+	 * <pre>{@code
 	 * new IProgressMonitor() {
 	 *     private final static int TIMEOUT = 500; //ms
 	 *     private long endTime;
@@ -302,6 +304,7 @@ void codeComplete(
 	 *     }
 	 *     ...
 	 * };
+	 * }
 	 * </pre>
 	 *
 	 * @param snippet the code snippet
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 7d50caa2419..fe4c17b3bb2 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
@@ -1514,8 +1514,8 @@ public final class JavaCore extends Plugin {
 	/**
 	 * Compiler option ID: Reporting a resource that is not closed properly.
 	 * <p>When enabled, the compiler will issue an error or a warning if
-	 *    a local variable holds a value of type <code>java.lang.AutoCloseable</code> (compliance>=1.7)
-	 *    or a value of type <code>java.io.Closeable</code> (compliance<=1.6) and if
+	 *    a local variable holds a value of type <code>java.lang.AutoCloseable</code> (compliance&gt;=1.7)
+	 *    or a value of type <code>java.io.Closeable</code> (compliance&lt;=1.6) and if
 	 *    flow analysis shows that the method <code>close()</code> is not invoked locally on that value.</p>
 	 * <dl>
 	 * <dt>Option id:</dt><dd><code>"org.eclipse.jdt.core.compiler.problem.unclosedCloseable"</code></dd>
@@ -2921,7 +2921,7 @@ public final class JavaCore extends Plugin {
 	 *    one of the proposed suffixes.</p>
 	 * <dl>
 	 * <dt>Option id:</dt><dd><code>"org.eclipse.jdt.core.codeComplete.staticFieldSuffixes"</code></dd>
-	 * <dt>Possible values:</dt><dd><code>{ "&lt;suffix&gt;[,&lt;suffix&gt;]*" }</code>< where <code>&lt;suffix&gt;</code> is a String without any wild-card</dd>
+	 * <dt>Possible values:</dt><dd>{@code  "<suffix>[,<suffix>]*" }&lt; where {@code <suffix> } is a String without any wild-card</dd>
 	 * <dt>Default:</dt><dd><code>""</code></dd>
 	 * </dl>
 	 * @since 2.1
@@ -2934,7 +2934,7 @@ public final class JavaCore extends Plugin {
 	 *    one of the proposed suffixes.</p>
 	 * <dl>
 	 * <dt>Option id:</dt><dd><code>"org.eclipse.jdt.core.codeComplete.staticFinalFieldSuffixes"</code></dd>
-	 * <dt>Possible values:</dt><dd><code>{ "&lt;suffix&gt;[,&lt;suffix&gt;]*" }</code>< where <code>&lt;suffix&gt;</code> is a String without any wild-card</dd>
+	 * <dt>Possible values:</dt><dd>{@code "<suffix>[<suffix>]*" }< where {@code <suffix>} is a String without any wild-card</dd>
 	 * <dt>Default:</dt><dd><code>""</code></dd>
 	 * </dl>
 	 * @since 3.5
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 248cde795f8..ce04a782271 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
@@ -51,7 +51,9 @@
  * </p>
  * <p>
  * The syntax for a type signature is:
+ * </p>
  * <pre>
+ * {@code
  * TypeSignature ::=
  *     "B"  // byte
  *   | "C"  // char
@@ -94,9 +96,11 @@
  * OptionalTypeParameters ::=
  *     "&lt;" + FormalTypeParameterSignature+ + "&gt;"
  *   |
+ * }
  * </pre>
  * <p>
  * Examples:
+ * </p>
  * <ul>
  *   <li><code>"[[I"</code> denotes <code>int[][]</code></li>
  *   <li><code>"Ljava.lang.String;"</code> denotes <code>java.lang.String</code> in compiled code</li>
@@ -109,13 +113,17 @@
  * </ul>
  * <p>
  * The syntax for a method signature is:
+ * </p>
  * <pre>
+ * {@code
  * MethodSignature ::= OptionalTypeParameters + "(" + ParamTypeSignature* + ")" + ReturnTypeSignature
  * ParamTypeSignature ::= TypeSignature
  * ReturnTypeSignature ::= TypeSignature
+ * }
  * </pre>
  * <p>
  * Examples:
+ * </p>
  * <ul>
  *   <li><code>"()I"</code> denotes <code>int foo()</code></li>
  *   <li><code>"([Ljava.lang.String;)V"</code> denotes <code>void foo(java.lang.String[])</code> in compiled code</li>
@@ -123,7 +131,9 @@
  * </ul>
  * <p>
  * The syntax for a formal type parameter signature is:
+ * </p>
  * <pre>
+ * {@code
  * FormalTypeParameterSignature ::=
  *     TypeVariableName + OptionalClassBound + InterfaceBound*
  * TypeVariableName ::= Identifier
@@ -132,9 +142,11 @@
  *   | ":" + TypeSignature
  * InterfaceBound ::=
  *     ":" + TypeSignature
+ * }
  * </pre>
  * <p>
  * Examples:
+ * </p>
  * <ul>
  *   <li><code>"X:"</code> denotes <code>X</code></li>
  *   <li><code>"X:QReader;"</code> denotes <code>X extends Reader</code> in source code</li>
@@ -275,7 +287,7 @@ public final class Signature {
 
 	/**
 	 * Character constant indicating a union type in a
-	 * signature. Value is <code>'&'</code>.
+	 * signature. Value is <code>'&amp;'</code>.
 	 *
 	 * @since 3.14
 	 */
@@ -1808,11 +1820,11 @@ public static String[] getParameterTypes(String methodSignature) throws IllegalA
  * <p>
  * For example:
  * <pre>
- * <code>
+ * {@code
  * getQualifier({'j', 'a', 'v', 'a', '.', 'l', 'a', 'n', 'g', '.', 'O', 'b', 'j', 'e', 'c', 't'}) -> {'j', 'a', 'v', 'a', '.', 'l', 'a', 'n', 'g'}
  * getQualifier({'O', 'u', 't', 'e', 'r', '.', 'I', 'n', 'n', 'e', 'r'}) -> {'O', 'u', 't', 'e', 'r'}
  * getQualifier({'j', 'a', 'v', 'a', '.', 'u', 't', 'i', 'l', '.', 'L', 'i', 's', 't', '<', 'j', 'a', 'v', 'a', '.', 'l', 'a', 'n', 'g', '.', 'S', 't', 'r', 'i', 'n', 'g', '>'}) -> {'j', 'a', 'v', 'a', '.', 'u', 't', 'i', 'l'}
- * </code>
+ * }
  * </pre>
  *
  * @param name the name
@@ -2139,12 +2151,12 @@ public static String getSimpleName(String name) {
  * <p>
  * For example:
  * <pre>
- * <code>
+ * {@code
  * getSimpleNames({'j', 'a', 'v', 'a', '.', 'l', 'a', 'n', 'g', '.', 'O', 'b', 'j', 'e', 'c', 't'}) -> {{'j', 'a', 'v', 'a'}, {'l', 'a', 'n', 'g'}, {'O', 'b', 'j', 'e', 'c', 't'}}
  * getSimpleNames({'O', 'b', 'j', 'e', 'c', 't'}) -> {{'O', 'b', 'j', 'e', 'c', 't'}}
  * getSimpleNames({}) -> {}
  * getSimpleNames({'j', 'a', 'v', 'a', '.', 'u', 't', 'i', 'l', '.', 'L', 'i', 's', 't', '<', 'j', 'a', 'v', 'a', '.', 'l', 'a', 'n', 'g', '.', 'S', 't', 'r', 'i', 'n', 'g', '>'}) -> {{'j', 'a', 'v', 'a'}, {'l', 'a', 'n', 'g'}, {'L', 'i', 's', 't', '<', 'j', 'a', 'v', 'a', '.', 'l', 'a', 'n', 'g', '.', 'S', 't', 'r', 'i', 'n', 'g'}}
- * </code>
+ * }
  * </pre>
  *
  * @param name the name
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/WorkingCopyOwner.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/WorkingCopyOwner.java
index 035906cb4a5..b89d74e70e1 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/WorkingCopyOwner.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/WorkingCopyOwner.java
@@ -104,7 +104,7 @@ public IProblemRequestor getProblemRequestor(ICompilationUnit workingCopy) {
 	 * types that would normally be available by returning an empty source for
 	 * the given type and package.</p>
 	 * <p>Example of use:
-	 * <pre>
+	 * <pre>{@code
 	 * WorkingCopyOwner owner = new WorkingCopyOwner() {
 	 *   public String findSource(String typeName, String packageName) {
 	 *     if ("to.be".equals(packageName) && "Generated".equals(typeName)) {
@@ -135,6 +135,7 @@ public IProblemRequestor getProblemRequestor(ICompilationUnit workingCopy) {
 	 * parser.setWorkingCopyOwner(owner);
 	 * CompilationUnit cu = (CompilationUnit) parser.createAST(null);
 	 * assert cu.getProblems().length == 0;
+	 * }
 	 * </pre>
 	 *
 	 * @param typeName the simple name of the type to lookup
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 d3d1fb2090b..198841fddde 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
@@ -191,7 +191,7 @@ public void codeComplete(
 	 * assist operation when a specified amount of time is reached could be used.
 	 * </p>
 	 *
-	 * <pre>
+	 * <pre>{@code
 	 * new IProgressMonitor() {
 	 *     private final static int TIMEOUT = 500; //ms
 	 *     private long endTime;
@@ -203,6 +203,7 @@ public void codeComplete(
 	 *     }
 	 *     ...
 	 * };
+	 * }
 	 * </pre>
 	 *
 	 * @param codeSnippet the code snippet to complete in
@@ -278,7 +279,7 @@ public void codeComplete(
 	 * assist operation when a specified amount of time is reached could be used.
 	 * </p>
 	 *
-	 * <pre>
+	 * <pre>{@code
 	 * new IProgressMonitor() {
 	 *     private final static int TIMEOUT = 500; //ms
 	 *     private long endTime;
@@ -290,6 +291,7 @@ public void codeComplete(
 	 *     }
 	 *     ...
 	 * };
+	 * }
 	 * </pre>
 	 *
 	 * @param codeSnippet the code snippet to complete in
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/jdom/IDOMMethod.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/jdom/IDOMMethod.java
index 86cf075b669..c6b389a5a1c 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/jdom/IDOMMethod.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/jdom/IDOMMethod.java
@@ -100,7 +100,7 @@ public interface IDOMMethod extends IDOMMember {
  * Returns an empty array if this method has no formal type parameters.
  * <p>Formal type parameters are as they appear in the source
  * code; for example:
- * <code>"X extends List&lt;String&gt; & Serializable"</code>.
+ * <code>"X extends List&lt;String&gt; &amp; Serializable"</code>.
  * </p>
  *
  * @return the formal type parameters of this method,
@@ -190,7 +190,7 @@ public interface IDOMMethod extends IDOMMember {
  * Sets the formal type parameters for this method.
  * <p>Formal type parameters are given as they appear in the source
  * code; for example:
- * <code>"X extends List&lt;String&gt; & Serializable"</code>.
+ * <code>"X extends List&lt;String&gt; &amp; Serializable"</code>.
  * </p>
  *
  * @param typeParameters the formal type parameters of this method,
diff --git a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/jdom/IDOMType.java b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/jdom/IDOMType.java
index 82ce424d5af..7fb26ba8a30 100644
--- a/org.eclipse.jdt.core/model/org/eclipse/jdt/core/jdom/IDOMType.java
+++ b/org.eclipse.jdt.core/model/org/eclipse/jdt/core/jdom/IDOMType.java
@@ -52,7 +52,7 @@ public interface IDOMType extends IDOMMember {
  * Returns an empty array if this method has no formal type parameters.
  * <p>Formal type parameters are as they appear in the source
  * code; for example:
- * <code>"X extends List&lt;String&gt; & Serializable"</code>.
+ * <code>"X extends List&lt;String&gt; &amp; Serializable"</code>.
  * </p>
  *
  * @return the formal type parameters of this type,
@@ -163,7 +163,7 @@ public interface IDOMType extends IDOMMember {
  * Sets the formal type parameters for this type.
  * <p>Formal type parameters are given as they appear in the source
  * code; for example:
- * <code>"X extends List&lt;String&gt; & Serializable"</code>.
+ * <code>"X extends List&lt;String&gt; &amp Serializable"</code>.
  * </p>
  *
  * @param typeParameters the formal type parameters of this type,