Issue 1275 broken javadoc

log4j-api/src/main/java/org/apache/logging/log4j/BridgeAware.java

@@ -24,10 +24,10 @@
 public interface BridgeAware {
 
     /**
-     * Fully qualified class name of the entry point to the logging system. This
+     * To set fully qualified class name of the entry point to the logging system. This
      * class will not appear in the location information.
      *
-     * @param fqcn
+     * @param fqcn fully qualified class name
      */
     void setEntryPoint(final String fqcn);
 }

log4j-api/src/main/java/org/apache/logging/log4j/Level.java

@@ -28,7 +28,9 @@
 
 /**
  * Levels used for identifying the severity of an event. Levels are organized from most specific to least:
+ * <p>
  * <table>
+ * <caption>Level names with description</caption>
  * <tr>
  * <th>Name</th>
  * <th>Description</th>
@@ -66,6 +68,7 @@
  * <td>All events should be logged.</td>
  * </tr>
  * </table>
+ * </p>
  * <p>
  * Typically, configuring a level in a filter or on a logger will cause logging events of that level and those that are
  * more specific to pass through the filter. A special level, {@link #ALL}, is guaranteed to capture all levels when

log4j-api/src/main/java/org/apache/logging/log4j/message/AbstractMessageFactory.java

@@ -24,7 +24,9 @@
  * <p>
  * This class is immutable.
  * </p>
- * <h4>Note to implementors</h4>
+ * <p>
+ * <strong>Note to implementors:</strong>
+ * </p>
  * <p>
  * Subclasses can implement the {@link MessageFactory2} methods when they can most effectively build {@link Message}
  * instances. If a subclass does not implement {@link MessageFactory2} methods, these calls are routed through

log4j-api/src/main/java/org/apache/logging/log4j/message/FormattedMessageFactory.java

@@ -20,7 +20,9 @@
  * Creates {@link FormattedMessage} instances for {@link MessageFactory2} methods (and {@link MessageFactory} by
  * extension.)
  *
- * <h4>Note to implementors</h4>
+ * <p>
+ * <strong>Note to implementors:</strong>
+ * </p>
  * <p>
  * This class implements all {@link MessageFactory2} methods.
  * </p>

log4j-api/src/main/java/org/apache/logging/log4j/message/LocalizedMessageFactory.java

@@ -22,7 +22,9 @@
  * Creates {@link FormattedMessage} instances for {@link MessageFactory2} methods (and {@link MessageFactory} by
  * extension.)
  *
- * <h4>Note to implementors</h4>
+ * <p>
+ * <strong>Note to implementors:</strong>
+ * </p>
  * <p>
  * This class does <em>not</em> implement any {@link MessageFactory2} methods and lets the superclass funnel those calls
  * through {@link #newMessage(String, Object...)}.

log4j-api/src/main/java/org/apache/logging/log4j/message/MessageFormatMessageFactory.java

@@ -19,8 +19,9 @@
 /**
  * Creates {@link FormattedMessage} instances for {@link MessageFactory2} methods (and {@link MessageFactory} by
  * extension.)
- *
- * <h4>Note to implementors</h4>
+ * <p>
+ * <strong>Note to implementors:</strong>
+ * </p>
  * <p>
  * This class implements all {@link MessageFactory2} methods.
  * </p>

log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterConsumer.java

@@ -35,7 +35,7 @@ public interface ParameterConsumer<S> {
      *
      * @param parameter the parameter
      * @param parameterIndex Index of the parameter
-     * @param state
+     * @param state the state data
      */
     void accept(Object parameter, int parameterIndex, S state);
 

log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterizedMessageFactory.java

@@ -29,7 +29,9 @@
  * This class is immutable.
  * </p>
  *
- * <h4>Note to implementors</h4>
+ * <p>
+ * <strong>Note to implementors:</strong>
+ * </p>
  * <p>
  * This class implements all {@link MessageFactory2} methods.
  * </p>

log4j-api/src/main/java/org/apache/logging/log4j/message/ParameterizedNoReferenceMessageFactory.java

@@ -31,7 +31,9 @@
  * <p>
  * This class is immutable.
  * </p>
- * <h4>Note to implementors</h4>
+ * <p>
+ * <strong>Note to implementors:</strong>
+ * </p>
  * <p>
  * This class does <em>not</em> implement any {@link MessageFactory2} methods and lets the superclass funnel those calls
  * through {@link #newMessage(String, Object...)}.

log4j-api/src/main/java/org/apache/logging/log4j/message/SimpleMessageFactory.java

@@ -29,8 +29,9 @@
  * <p>
  * This class is immutable.
  * </p>
- *
- * <h4>Note to implementors</h4>
+ * <p>
+ * <strong>Note to implementors:</strong>
+ * </p>
  * <p>
  * This class implements all {@link MessageFactory2} methods.
  * </p>

log4j-api/src/main/java/org/apache/logging/log4j/message/StringFormattedMessage.java

@@ -29,7 +29,9 @@
 /**
  * Handles messages that consist of a format string conforming to {@link java.util.Formatter}.
  *
- * <h4>Note to implementors</h4>
+ * <p>
+ * <strong>Note to implementors:</strong>
+ * </p>
  * <p>
  * This class implements the unrolled args API even though StringFormattedMessage does not. This leaves the room for
  * StringFormattedMessage to unroll itself later.

log4j-api/src/main/java/org/apache/logging/log4j/message/StringFormatterMessageFactory.java

@@ -28,7 +28,9 @@
  * <p>
  * This class is immutable.
  * </p>
- * <h4>Note to implementors</h4>
+ * <p>
+ * <strong>Note to implementors:</strong>
+ * </p>
  * <p>
  * This class implements all {@link MessageFactory2} methods.
  * </p>

log4j-api/src/main/java/org/apache/logging/log4j/message/StructuredDataId.java

@@ -79,9 +79,9 @@ public StructuredDataId(final String name, final int maxLength) {
 
     /**
      *
-     * @param name
-     * @param required
-     * @param optional
+     * @param name The name portion of the id.
+     * @param required The list of keys that are required for this id.
+     * @param optional The list of keys that are optional for this id.
      */
     public StructuredDataId(final String name, final String[] required, final String[] optional) {
         this(name, required, optional, MAX_LENGTH);
@@ -93,6 +93,7 @@ public StructuredDataId(final String name, final String[] required, final String
      * @param name The name portion of the id.
      * @param required The list of keys that are required for this id.
      * @param optional The list of keys that are optional for this id.
+     * @param maxLength The maximum length of the id's name.
      * @since 2.9
      */
     public StructuredDataId(final String name, final String[] required, final String[] optional, int maxLength) {

log4j-api/src/main/java/org/apache/logging/log4j/spi/MutableThreadContextStack.java

@@ -47,7 +47,7 @@ public MutableThreadContextStack() {
 
     /**
      * Constructs a new instance.
-     * @param list
+     * @param list Initial elements to be stored in this stack implementation.
      */
     public MutableThreadContextStack(final List<String> list) {
         this.list = new ArrayList<>(list);

log4j-api/src/main/java/org/apache/logging/log4j/util/EnglishEnums.java

@@ -26,7 +26,7 @@
  * Helps convert English Strings to English Enum values.
  * </p>
  * <p>
- * Enum name arguments are converted internally to upper case with the {@linkplain Locale#ENGLISH ENGLISH} locale to
+ * Enum name arguments are converted internally to upper case with the {@linkplain java.util.Locale#ENGLISH ENGLISH} locale to
  * avoid problems on the Turkish locale. Do not use with Turkish enum values.
  * </p>
  */
@@ -38,7 +38,7 @@ private EnglishEnums() {
     /**
      * Returns the Result for the given string.
      * <p>
-     * The {@code name} is converted internally to upper case with the {@linkplain Locale#ENGLISH ENGLISH} locale to
+     * The {@code name} is converted internally to upper case with the {@linkplain java.util.Locale#ENGLISH ENGLISH} locale to
      * avoid problems on the Turkish locale. Do not use with Turkish enum values.
      * </p>
      *
@@ -54,7 +54,7 @@ public static <T extends Enum<T>> T valueOf(final Class<T> enumType, final Strin
     /**
      * Returns an enum value for the given string.
      * <p>
-     * The {@code name} is converted internally to upper case with the {@linkplain Locale#ENGLISH ENGLISH} locale to
+     * The {@code name} is converted internally to upper case with the {@linkplain java.util.Locale#ENGLISH ENGLISH} locale to
      * avoid problems on the Turkish locale. Do not use with Turkish enum values.
      * </p>
      *

log4j-api/src/main/java/org/apache/logging/log4j/util/ProcessIdUtil.java

@@ -21,7 +21,7 @@
 import java.lang.reflect.Method;
 
 /**
- * @Since 2.9
+ * @since 2.9
  */
 public class ProcessIdUtil {
 

log4j-core/src/main/java/org/apache/logging/log4j/core/appender/AbstractOutputStreamAppender.java

@@ -129,6 +129,10 @@ protected AbstractOutputStreamAppender(final String name, final Layout<? extends
      *
      * @param name The name of the Appender.
      * @param layout The layout to format the message.
+     * @param filter The filter to associate with the Appender.
+     * @param ignoreExceptions If true, exceptions will be logged and suppressed.
+     *                         If false errors will be logged and then passed to the application.
+     * @param immediateFlush Underlying output stream will be flushed at the end of each append operation.
      * @param properties optional properties
      * @param manager The OutputStreamManager.
      */

log4j-core/src/main/java/org/apache/logging/log4j/core/appender/AbstractWriterAppender.java

@@ -54,6 +54,13 @@ public abstract class AbstractWriterAppender<M extends WriterManager> extends Ab
      *            The name of the Appender.
      * @param layout
      *            The layout to format the message.
+     * @param filter
+     *            The filter to associate with the Appender.
+     * @param ignoreExceptions
+     *            If true, exceptions will be logged and suppressed.
+     *            If false errors will be logged and then passed to the application.
+     * @param immediateFlush
+     *            Underlying writer will be flushed at the end of each append operation.
      * @param properties
      *            Optional properties.
      * @param manager

log4j-core/src/main/java/org/apache/logging/log4j/core/appender/db/jdbc/JdbcDatabaseManager.java

@@ -421,13 +421,14 @@ public static JdbcDatabaseManager getManager(final String name, final int buffer
      *
      * @param name The name of the manager, which should include connection details and hashed passwords where possible.
      * @param bufferSize The size of the log event buffer.
-     * @param layout
+     * @param layout the Appender-level layout
      * @param connectionSource The source for connections to the database.
      * @param tableName The name of the database table to insert log events into.
      * @param columnConfigs Configuration information about the log table columns.
      * @param columnMappings column mapping configuration (including type conversion).
-     * @param reconnectIntervalMillis
-     * @param immediateFail
+     * @param reconnectIntervalMillis How often to reconnect to the database when a SQL exception is detected.
+     * @param immediateFail Whether to fail immediately with a {@link AppenderLoggingException} when connecting
+     * to JDBC fails.
      * @return a new or existing JDBC manager as applicable.
      * @deprecated use
      * {@link #getManager(String, int, Layout, ConnectionSource, String, ColumnConfig[], ColumnMapping[], boolean, long)}

log4j-core/src/main/java/org/apache/logging/log4j/core/appender/rolling/action/DeleteAction.java

@@ -189,8 +189,8 @@ protected FileVisitor<Path> createFileVisitor(final Path visitorBaseDir, final L
      *            href="http://logging.apache.org/log4j/2.x/manual/configuration.html#StatusMessages">status logger</a>
      *            at INFO level. Users can use this to do a dry run to test if their configuration works as expected.
      *            Default is false.
-     * @param PathSorter a plugin implementing the {@link PathSorter} interface
-     * @param PathConditions an array of path conditions (if more than one, they all need to accept a path before it is
+     * @param sorterParameter a plugin implementing the {@link PathSorter} interface
+     * @param pathConditions an array of path conditions (if more than one, they all need to accept a path before it is
      *            deleted).
      * @param config The Configuration.
      * @return A DeleteAction.

log4j-core/src/main/java/org/apache/logging/log4j/core/appender/rolling/action/ScriptCondition.java

@@ -36,7 +36,7 @@
 
 /**
  * A condition of the {@link DeleteAction} where a user-provided script selects the files to delete from a provided
- * list. The specified script may be a {@link Script}, a {@link ScriptFile} or a {@link ScriptRef}.
+ * list. The specified script may be a {@link org.apache.logging.log4j.core.script.Script}, a {@link ScriptFile} or a {@link ScriptRef}.
  *
  * @see #createCondition(AbstractScript, Configuration)
  */
@@ -61,9 +61,9 @@ public ScriptCondition(final AbstractScript script, final Configuration configur
     /**
      * Executes the script
      *
-     * @param baseDir
-     * @param candidates
-     * @return
+     * @param basePath base directory for files to delete
+     * @param candidates a list of paths, that can be deleted by the script
+     * @return a list of paths selected to delete by the script execution
      */
     @SuppressWarnings("unchecked")
     public List<PathWithAttributes> selectFilesToDelete(final Path basePath, final List<PathWithAttributes> candidates) {
@@ -81,15 +81,15 @@ public List<PathWithAttributes> selectFilesToDelete(final Path basePath, final L
     /**
      * Creates the ScriptCondition.
      *
-     * @param script The script to run. This may be a {@link Script}, a {@link ScriptFile} or a {@link ScriptRef}. The
+     * @param script The script to run. This may be a {@link org.apache.logging.log4j.core.script.Script}, a {@link ScriptFile} or a {@link ScriptRef}. The
      *            script must return a {@code List<PathWithAttributes>}. When the script is executed, it is provided the
      *            following bindings:
      *            <ul>
      *            <li>basePath - the directory from where the {@link DeleteAction Delete} action started scanning for
      *            files to delete. Can be used to relativize the paths in the pathList.</li>
-     *            <li>pathList - a {@code java.util.List} containing {@link PathWithAttribute} objects. (The script is
+     *            <li>pathList - a {@code java.util.List} containing {@link org.apache.logging.log4j.core.appender.rolling.action.PathWithAttributes} objects. (The script is
      *            free to modify and return this list.)</li>
-     *            <li>substitutor - a {@link StrSubstitutor} that can be used to look up variables embedded in the base
+     *            <li>substitutor - a {@link org.apache.logging.log4j.core.lookup.StrSubstitutor} that can be used to look up variables embedded in the base
      *            dir or other properties
      *            <li>statusLogger - the {@link StatusLogger} that can be used to log events during script execution
      *            <li>any properties declared in the configuration</li>

log4j-core/src/main/java/org/apache/logging/log4j/core/appender/rolling/action/SortingVisitor.java

@@ -40,10 +40,9 @@ public class SortingVisitor extends SimpleFileVisitor<Path> {
     private final List<PathWithAttributes> collected = new ArrayList<>();
 
     /**
-     * Constructs a new DeletingVisitor.
+     * Constructs a new SortingVisitor.
      *
-     * @param basePath used to relativize paths
-     * @param pathFilters objects that need to confirm whether a file can be deleted
+     * @param sorter Interface implementation which can sort paths.
      */
     public SortingVisitor(final PathSorter sorter) {
         this.sorter = Objects.requireNonNull(sorter, "sorter");

log4j-core/src/main/java/org/apache/logging/log4j/core/appender/routing/PurgePolicy.java

@@ -31,14 +31,14 @@ public interface PurgePolicy {
 
     /**
      * @param key routed appender key
-     * @param event
+     * @param event Provides contextual information about a logged message.
      */
     void update(String key, LogEvent event);
 
     /**
      * Initializes with routing appender
      *
-     * @param routingAppender
+     * @param routingAppender the routed appender for purging
      */
     void initialize(RoutingAppender routingAppender);
 

log4j-core/src/main/java/org/apache/logging/log4j/core/async/DiscardingAsyncQueueFullPolicy.java

@@ -27,7 +27,7 @@
  * Discarding router extends the DefaultAsyncQueueFullPolicy by first verifying if the queue is fuller than the specified
  * threshold ratio; if this is the case, log events {@linkplain Level#isMoreSpecificThan(Level) more specific} than
  * the specified threshold level are dropped. If this is not the case, the {@linkplain DefaultAsyncQueueFullPolicy
- * default routing rules hold.
+ * default routing} rules hold.
  */
 public class DiscardingAsyncQueueFullPolicy extends DefaultAsyncQueueFullPolicy {
     private static final Logger LOGGER = StatusLogger.getLogger();

log4j-core/src/main/java/org/apache/logging/log4j/core/config/DefaultAdvertiser.java

@@ -39,7 +39,7 @@ public Object advertise(final Map<String, String> properties) {
 
     /**
      * Does nothing.
-     * @param advertisedObject
+     * @param advertisedObject the advertised object
      */
     @Override
     public void unadvertise(final Object advertisedObject) {

log4j-core/src/main/java/org/apache/logging/log4j/core/config/Property.java

@@ -79,7 +79,7 @@ public String getValue() {
 
     /**
      * Returns {@code true} if the value contains a substitutable property that requires a lookup to be resolved.
-     * @return {@code true} if the value contains {@code "${"}, {@code false} otherwise
+     * @return {@code true} if the value contains {@code "${}"}, {@code false} otherwise
      */
     public boolean isValueNeedsLookup() {
         return valueNeedsLookup;

log4j-core/src/main/java/org/apache/logging/log4j/core/config/plugins/convert/Base64Converter.java

@@ -25,7 +25,7 @@
 import org.apache.logging.log4j.util.LoaderUtil;
 
 /**
- * @Since 2.9
+ * @since 2.9
  */
 public class Base64Converter {
 

log4j-core/src/main/java/org/apache/logging/log4j/core/config/plugins/convert/HexConverter.java

@@ -20,7 +20,7 @@
  * Converts Strings to hex. This is used in place of java.xml.bind.DataTypeConverter which is not available by
  * default in Java 9.
  *
- * @Since 2.9
+ * @since 2.9
  */
 public class HexConverter {
 

log4j-core/src/main/java/org/apache/logging/log4j/core/filter/RegexFilter.java

@@ -119,8 +119,8 @@ public String toString() {
      * @param mismatch
      *        The action to perform when a mismatch occurs.
      * @return The RegexFilter.
-     * @throws IllegalAccessException
-     * @throws IllegalArgumentException
+     * @throws IllegalAccessException  When there is no access to the definition of the specified member.
+     * @throws IllegalArgumentException When passed an illegal or inappropriate argument.
      */
     // TODO Consider refactoring to use AbstractFilter.AbstractFilterBuilder
     @PluginFactory

log4j-core/src/main/java/org/apache/logging/log4j/core/filter/StringMatchFilter.java

@@ -158,7 +158,7 @@ public static class Builder extends AbstractFilterBuilder<StringMatchFilter.Buil
 
         /**
          * Sets the logging level to use.
-         * @param level the logging level to use.
+         * @param text the logging level to use
          * @return this
          */
         public StringMatchFilter.Builder setMatchString(final String text) {