Bug 545691 - Javadoc errors in jdt.core bundles

- fix javadoc errors/warnings in jdt.core classes

Change-Id: I4708bb425398235675948df94280263982184a98
Signed-off-by: Jeff Johnston <jjohnstn@redhat.com>

org.eclipse.jdt.annotation/src/org/eclipse/jdt/annotation/Checks.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2016 Stephan Herrmann and others.
+ * Copyright (c) 2016, 2019 Stephan Herrmann and others.
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -83,8 +83,8 @@
  * <dt>computations</dt>
  * <dd>Methods {@link #ifNonNull(Object, Consumer)}, {@link #applyIfNonNull(Object, Function)},
  * {@link #applyIfNonNullElse(Object, Function, Object)} and {@link #applyIfNonNullElseGet(Object, Function, Supplier)}
- * feed unsafe values into a given functional expression in a null-safe way.
- * <dl>
+ * feed unsafe values into a given functional expression in a null-safe way.</dd>
+ * </dl>
  * 
  * @since 2.1
  */

org.eclipse.jdt.apt.core/src/com/sun/mirror/apt/AnnotationProcessorEnvironment.java

@@ -46,7 +46,7 @@
  *
  * <p> When an annotation processing tool is invoked, it is given a
  * set of type declarations on which to operate.  These
- * are refered to as the <i>specified</i> types.
+ * are referred to as the <i>specified</i> types.
  * The type declarations said to be <i>included</i> in this invocation
  * consist of the specified types and any types nested within them.
  *
@@ -65,11 +65,11 @@ public interface AnnotationProcessorEnvironment {
     /**
      * Returns the options passed to the annotation processing tool.
      * Options are returned in the form of a map from option name
-     * (such as <tt>"-encoding"</tt>) to option value.
-     * For an option with no value (such as <tt>"-help"</tt>), the
-     * corresponding value in the map is <tt>null</tt>.
+     * (such as <code>"-encoding"</code>) to option value.
+     * For an option with no value (such as <code>"-help"</code>), the
+     * corresponding value in the map is <code>null</code>.
      *
-     * <p> Options beginning with <tt>"-A"</tt> are <i>processor-specific.</i>
+     * <p> Options beginning with <code>"-A"</code> are <i>processor-specific.</i>
      * Such options are unrecognized by the tool, but intended to be used by
      * some annotation processor.
      *

org.eclipse.jdt.apt.core/src/com/sun/mirror/apt/AnnotationProcessorFactory.java

@@ -44,7 +44,7 @@
  * annotation types.
  * The factory is said to <i>support</i> these types.
  *
- * <p> Each implementation of an <tt>AnnotationProcessorFactory</tt>
+ * <p> Each implementation of an <code>AnnotationProcessorFactory</code>
  * must provide a public no-argument constructor to be used by tools to
  * instantiate the factory.
  *
@@ -61,9 +61,9 @@ public interface AnnotationProcessorFactory {
      * processors it may create.
      * Only {@linkplain AnnotationProcessorEnvironment#getOptions()
      * processor-specific} options are included, each of which begins
-     * with <tt>"-A"</tt>.  For example, if this factory recognizes
-     * options such as <tt>-Adebug -Aloglevel=3</tt>, it will
-     * return the strings <tt>"-Adebug"</tt> and <tt>"-Aloglevel"</tt>.
+     * with <code>"-A"</code>.  For example, if this factory recognizes
+     * options such as <code>-Adebug -Aloglevel=3</code>, it will
+     * return the strings <code>"-Adebug"</code> and <code>"-Aloglevel"</code>.
      *
      * <p> A tool might use this information to determine if any
      * options provided by a user are unrecognized by any processor,
@@ -78,10 +78,10 @@ public interface AnnotationProcessorFactory {
      * Returns the names of the annotation types supported by this factory.
      * An element of the result may be the canonical (fully qualified) name
      * of a supported annotation type.  Alternately it may be of the form
-     * <tt>"<i>name</i>.*"</tt>
+     * <code>"<i>name</i>.*"</code>
      * representing the set of all annotation types
-     * with canonical names beginning with <tt>"<i>name</i>."</tt>
-     * Finally, <tt>"*"</tt> by itself represents the set of all
+     * with canonical names beginning with <code>"<i>name</i>."</code>
+     * Finally, <code>"*"</code> by itself represents the set of all
      * annotation types.
      *
      * @return the names of the annotation types supported by this factory
@@ -91,18 +91,18 @@ public interface AnnotationProcessorFactory {
     /**
      * Returns an annotation processor for a set of annotation
      * types. The set will be empty if the factory supports
-     * &quot;<tt>*</tt>&quot; and the specified type declarations have
+     * &quot;<code>*</code>&quot; and the specified type declarations have
      * no annotations.  Note that the set of annotation types may be
      * empty for other reasons, such as giving the factory an
      * opportunity to register a listener.  An
-     * <tt>AnnotationProcessorFactory</tt> must gracefully handle an
+     * <code>AnnotationProcessorFactory</code> must gracefully handle an
      * empty set of annotations; an appropriate response to an empty
      * set will often be returning {@link AnnotationProcessors#NO_OP}.
      *
      * @param atds type declarations of the annotation types to be processed
      * @param env  environment to use during processing
      * @return an annotation processor for the given annotation types,
-     *		or <tt>null</tt> if the types are not supported or the
+     *		or <code>null</code> if the types are not supported or the
      *		processor cannot be created
      */
     AnnotationProcessor getProcessorFor(Set<AnnotationTypeDeclaration> atds,

org.eclipse.jdt.apt.core/src/com/sun/mirror/apt/Filer.java

@@ -48,7 +48,7 @@
  * file system) where newly created files are placed:
  * one for new source files, and one for new class files.
  * (These might be specified on a tool's command line, for example,
- * using flags such as <tt>-s</tt> and <tt>-d</tt>.)
+ * using flags such as <code>-s</code> and <code>-d</code>.)
  * Auxiliary files may be created in either location.
  *
  * <p> During each run of an annotation processing tool, a file
@@ -74,7 +74,7 @@ public interface Filer {
      *
      * <p> The {@linkplain java.nio.charset.Charset charset} used to
      * encode the file is determined by the implementation.
-     * An annotation processing tool may have an <tt>-encoding</tt>
+     * An annotation processing tool may have an <code>-encoding</code>
      * flag or the like for specifying this.  It will typically use
      * the platform's default encoding if none is specified.
      *
@@ -103,7 +103,7 @@ public interface Filer {
      * named relative to some package (as are source and binary files),
      * and from there by an arbitrary pathname.  In a loose sense, the
      * pathname of the new file will be the concatenation of
-     * <tt>loc</tt>, <tt>pkg</tt>, and <tt>relPath</tt>.
+     * <code>loc</code>, <code>pkg</code>, and <code>relPath</code>.
      *
      * <p> A {@linkplain java.nio.charset.Charset charset} for
      * encoding the file may be provided.  If none is given, the
@@ -131,7 +131,7 @@ PrintWriter createTextFile(Location loc,
      * named relative to some package (as are source and binary files),
      * and from there by an arbitrary pathname.  In a loose sense, the
      * pathname of the new file will be the concatenation of
-     * <tt>loc</tt>, <tt>pkg</tt>, and <tt>relPath</tt>.
+     * <code>loc</code>, <code>pkg</code>, and <code>relPath</code>.
      *
      * @param loc location of the new file
      * @param pkg package relative to which the file should be named,

org.eclipse.jdt.apt.core/src/com/sun/mirror/apt/Messager.java

@@ -36,7 +36,7 @@
 
 
 /**
- * A <tt>Messager</tt> provides the way for
+ * A <code>Messager</code> provides the way for
  * an annotation processor to report error messages, warnings, and
  * other notices.
  *
@@ -50,7 +50,7 @@ public interface Messager {
 
     /**
      * Prints an error message.
-     * Equivalent to <tt>printError(null, msg)</tt>.
+     * Equivalent to <code>printError(null, msg)</code>.
      * @param msg  the message, or an empty string if none
      */
     void printError(String msg);
@@ -65,7 +65,7 @@ public interface Messager {
 
     /**
      * Prints a warning message.
-     * Equivalent to <tt>printWarning(null, msg)</tt>.
+     * Equivalent to <code>printWarning(null, msg)</code>.
      * @param msg  the message, or an empty string if none
      */
     void printWarning(String msg);
@@ -80,7 +80,7 @@ public interface Messager {
 
     /**
      * Prints a notice.
-     * Equivalent to <tt>printNotice(null, msg)</tt>.
+     * Equivalent to <code>printNotice(null, msg)</code>.
      * @param msg  the message, or an empty string if none
      */
     void printNotice(String msg);

org.eclipse.jdt.apt.core/src/com/sun/mirror/apt/RoundCompleteEvent.java

@@ -34,7 +34,7 @@
 /**
  * Event for the completion of a round of annotation processing.
  *
- * <p>While this class extends the serializable <tt>EventObject</tt>, it
+ * <p>While this class extends the serializable <code>EventObject</code>, it
  * cannot meaningfully be serialized because all of the annotation
  * processing tool's internal state would potentially be needed.
  *
@@ -48,7 +48,7 @@ public abstract class RoundCompleteEvent extends java.util.EventObject {
     private RoundState rs;
 
     /**
-     * The current <tt>AnnotationProcessorEnvironment</tt> is regarded
+     * The current <code>AnnotationProcessorEnvironment</code> is regarded
      * as the source of events.
      *
      * @param source The source of events

org.eclipse.jdt.apt.core/src/com/sun/mirror/apt/RoundState.java

@@ -41,26 +41,26 @@
  */
 public interface RoundState {
     /**
-     * Returns <tt>true</tt> if this was the last round of annotation
-     * processing; returns <tt>false</tt> if there will be a subsequent round.
+     * Returns <code>true</code> if this was the last round of annotation
+     * processing; returns <code>false</code> if there will be a subsequent round.
      */
     boolean finalRound();
 
     /**
-     * Returns <tt>true</tt> if an error was raised in this round of processing;
-     * returns <tt>false</tt> otherwise.
+     * Returns <code>true</code> if an error was raised in this round of processing;
+     * returns <code>false</code> otherwise.
      */
     boolean errorRaised();
 
     /**
-     * Returns <tt>true</tt> if new source files were created in this round of
-     * processing; returns <tt>false</tt> otherwise.
+     * Returns <code>true</code> if new source files were created in this round of
+     * processing; returns <code>false</code> otherwise.
      */
     boolean sourceFilesCreated();
 
     /**
-     * Returns <tt>true</tt> if new class files were created in this round of
-     * processing; returns <tt>false</tt> otherwise.
+     * Returns <code>true</code> if new class files were created in this round of
+     * processing; returns <code>false</code> otherwise.
      */
     boolean classFilesCreated();
 }

org.eclipse.jdt.apt.core/src/com/sun/mirror/declaration/AnnotationMirror.java

@@ -41,7 +41,7 @@
  * each element of an annotation type.
  *
  * <p> Annotations should not be compared using reference-equality
- * ("<tt>==</tt>").  There is no guarantee that any particular
+ * ("<code>==</code>").  There is no guarantee that any particular
  * annotation will always be represented by the same object.
  *
  * @author Joseph D. Darcy

org.eclipse.jdt.apt.core/src/com/sun/mirror/declaration/ClassDeclaration.java

@@ -44,7 +44,7 @@
  * its constructors.
  * Note that an {@linkplain EnumDeclaration enum} is a kind of class.
  *
- * <p> While a <tt>ClassDeclaration</tt> represents the <i>declaration</i>
+ * <p> While a <code>ClassDeclaration</code> represents the <i>declaration</i>
  * of a class, a {@link ClassType} represents a class <i>type</i>.
  * See {@link TypeDeclaration} for more on this distinction.
  *
@@ -64,7 +64,7 @@ public interface ClassDeclaration extends TypeDeclaration {
 
     /**
      * Returns the class type directly extended by this class.
-     * The only class with no superclass is <tt>java.lang.Object</tt>,
+     * The only class with no superclass is <code>java.lang.Object</code>,
      * for which this method returns null.
      *
      * @return the class type directly extended by this class, or null

org.eclipse.jdt.apt.core/src/com/sun/mirror/declaration/Declaration.java

@@ -65,7 +65,7 @@ public interface Declaration {
      * Tests whether an object represents the same declaration as this.
      *
      * @param obj  the object to be compared with this declaration
-     * @return <tt>true</tt> if the specified object represents the same
+     * @return <code>true</code> if the specified object represents the same
      *		declaration as this
      */
     @Override
@@ -75,7 +75,7 @@ public interface Declaration {
      * Returns the text of the documentation ("javadoc") comment of
      * this declaration.
      *
-     * @return the documentation comment of this declaration, or <tt>null</tt>
+     * @return the documentation comment of this declaration, or <code>null</code>
      *		if there is none
      */
     String getDocComment();
@@ -94,15 +94,15 @@ public interface Declaration {
      * present on this declaration.
      *
      * <p> The annotation returned by this method could contain an element
-     * whose value is of type <tt>Class</tt>.
+     * whose value is of type <code>Class</code>.
      * This value cannot be returned directly:  information necessary to
      * locate and load a class (such as the class loader to use) is
      * not available, and the class might not be loadable at all.
-     * Attempting to read a <tt>Class</tt> object by invoking the relevant
+     * Attempting to read a <code>Class</code> object by invoking the relevant
      * method on the returned annotation
      * will result in a {@link MirroredTypeException},
      * from which the corresponding {@link TypeMirror} may be extracted.
-     * Similarly, attempting to read a <tt>Class[]</tt>-valued element
+     * Similarly, attempting to read a <code>Class[]</code>-valued element
      * will result in a {@link MirroredTypesException}.
      *
      * <blockquote>
@@ -116,7 +116,7 @@ public interface Declaration {
      * </blockquote>
      *
      * @param <A>  the annotation type
-     * @param annotationType  the <tt>Class</tt> object corresponding to
+     * @param annotationType  the <code>Class</code> object corresponding to
      *		the annotation type
      * @return the annotation of this declaration having the specified type
      *
@@ -126,7 +126,7 @@ public interface Declaration {
 
     /**
      * Returns the modifiers of this declaration, excluding annotations.
-     * Implicit modifiers, such as the <tt>public</tt> and <tt>static</tt>
+     * Implicit modifiers, such as the <code>public</code> and <code>static</code>
      * modifiers of interface members, are included.
      *
      * @return the modifiers of this declaration in undefined order;
@@ -139,7 +139,7 @@ public interface Declaration {
      * The name of a generic type does not include any reference
      * to its formal type parameters.
      * For example, the simple name of the interface declaration
-     * {@code java.util.Set<E>} is <tt>"Set"</tt>.
+     * {@code java.util.Set<E>} is <code>"Set"</code>.
      * If this declaration represents the empty package, an empty
      * string is returned.
      * If it represents a constructor, the simple name of its
@@ -151,7 +151,7 @@ public interface Declaration {
 
     /**
      * Returns the source position of the beginning of this declaration.
-     * Returns <tt>null</tt> if the position is unknown or not applicable.
+     * Returns <code>null</code> if the position is unknown or not applicable.
      *
      * <p> This source position is intended for use in providing
      * diagnostics, and indicates only approximately where a declaration

org.eclipse.jdt.apt.core/src/com/sun/mirror/declaration/ExecutableDeclaration.java

@@ -49,10 +49,10 @@
 public interface ExecutableDeclaration extends MemberDeclaration {
 
     /**
-     * Returns <tt>true</tt> if this method or constructor accepts a variable
+     * Returns <code>true</code> if this method or constructor accepts a variable
      * number of arguments.
      *
-     * @return <tt>true</tt> if this method or constructor accepts a variable
+     * @return <code>true</code> if this method or constructor accepts a variable
      * number of arguments
      */
     boolean isVarArgs();
@@ -77,10 +77,10 @@ public interface ExecutableDeclaration extends MemberDeclaration {
 
     /**
      * Returns the exceptions and other throwables listed in this
-     * method or constructor's <tt>throws</tt> clause.
+     * method or constructor's <code>throws</code> clause.
      *
      * @return the exceptions and other throwables listed in the
-     * <tt>throws</tt> clause, or an empty collection if there are none
+     * <code>throws</code> clause, or an empty collection if there are none
      */
     Collection<ReferenceType> getThrownTypes();
 }

org.eclipse.jdt.apt.core/src/com/sun/mirror/declaration/FieldDeclaration.java

@@ -55,26 +55,26 @@ public interface FieldDeclaration extends MemberDeclaration {
 
     /**
      * Returns the value of this field if this field is a compile-time
-     * constant.  Returns <tt>null</tt> otherwise.
-     * The value will be of a primitive type or <tt>String</tt>.
+     * constant.  Returns <code>null</code> otherwise.
+     * The value will be of a primitive type or <code>String</code>.
      * If the value is of a primitive type, it is wrapped in the
      * appropriate wrapper class (such as {@link Integer}).
      *
      * @return the value of this field if this field is a compile-time
-     * constant, or <tt>null</tt> otherwise
+     * constant, or <code>null</code> otherwise
      */
     Object getConstantValue();
 
     /**
      * Returns the text of a <i>constant expression</i> representing the
      * value of this field if this field is a compile-time constant.
-     * Returns <tt>null</tt> otherwise.
-     * The value will be of a primitive type or <tt>String</tt>.
+     * Returns <code>null</code> otherwise.
+     * The value will be of a primitive type or <code>String</code>.
      * The text returned is in a form suitable for representing the value
      * in source code.
      *
      * @return the text of a constant expression if this field is a
-     *		compile-time constant, or <tt>null</tt> otherwise
+     *		compile-time constant, or <code>null</code> otherwise
      */
     String getConstantExpression();
 }

org.eclipse.jdt.apt.core/src/com/sun/mirror/declaration/InterfaceDeclaration.java

@@ -41,7 +41,7 @@
  * Note that an {@linkplain AnnotationTypeDeclaration annotation type} is
  * a kind of interface.
  *
- * <p> While an <tt>InterfaceDeclaration</tt> represents the
+ * <p> While an <code>InterfaceDeclaration</code> represents the
  * <i>declaration</i> of an interface, an {@link InterfaceType}
  * represents an interface <i>type</i>.
  * See {@link TypeDeclaration} for more on this distinction.