Javadoc fixes
diff --git a/log4j-1.2-api/src/main/java/org/apache/log4j/WriterAppender.java b/log4j-1.2-api/src/main/java/org/apache/log4j/WriterAppender.java
index f026bfa..147990f 100644
--- a/log4j-1.2-api/src/main/java/org/apache/log4j/WriterAppender.java
+++ b/log4j-1.2-api/src/main/java/org/apache/log4j/WriterAppender.java
@@ -95,6 +95,7 @@
/**
* Returns value of the <b>ImmediateFlush</b> option.
+ * @return the value of the immediate flush setting.
*/
public boolean getImmediateFlush() {
return immediateFlush;
@@ -113,6 +114,8 @@
* skipped, then it is likely that the last few log events will not
* be recorded on disk when the application exits. This is a high
* price to pay even for a 20% performance gain.
+ *
+ * @param value the value to set the immediate flush setting to.
*/
public void setImmediateFlush(boolean value) {
immediateFlush = value;
@@ -159,6 +162,7 @@
* <p>It checks whether there is a set output target and also if
* there is a set layout. If these checks fail, then the boolean
* value <code>false</code> is returned.
+ * @return true if appending is allowed, false otherwise.
*/
protected boolean checkEntryConditions() {
if (this.closed) {
@@ -222,6 +226,8 @@
* <code>encoding</code> property. If the encoding value is
* specified incorrectly the writer will be opened using the default
* system encoding (an error message will be printed to the LOGGER.
+ * @param os The OutputStream.
+ * @return The OutputStreamWriter.
*/
protected OutputStreamWriter createWriter(OutputStream os) {
OutputStreamWriter retval = null;
@@ -295,6 +301,7 @@
*
* <p>Most subclasses of <code>WriterAppender</code> will need to
* override this method.
+ * @param event The event to log.
*
* @since 0.9.0
*/
@@ -369,6 +376,8 @@
/**
* Determines whether the writer should be flushed after
* this event is written.
+ * @param event The event to log.
+ * @return true if the writer should be flushed.
*
* @since 1.2.16
*/
diff --git a/log4j-1.2-api/src/main/java/org/apache/log4j/bridge/AppenderAdapter.java b/log4j-1.2-api/src/main/java/org/apache/log4j/bridge/AppenderAdapter.java
index f2dd2c1..1ae0369 100644
--- a/log4j-1.2-api/src/main/java/org/apache/log4j/bridge/AppenderAdapter.java
+++ b/log4j-1.2-api/src/main/java/org/apache/log4j/bridge/AppenderAdapter.java
@@ -38,6 +38,7 @@
/**
* Constructor.
+ * @param appender The Appender to wrap.
*/
public AppenderAdapter(Appender appender) {
this.appender = appender;
diff --git a/log4j-1.2-api/src/main/java/org/apache/log4j/bridge/LogEventAdapter.java b/log4j-1.2-api/src/main/java/org/apache/log4j/bridge/LogEventAdapter.java
index 9de0476..894045e 100644
--- a/log4j-1.2-api/src/main/java/org/apache/log4j/bridge/LogEventAdapter.java
+++ b/log4j-1.2-api/src/main/java/org/apache/log4j/bridge/LogEventAdapter.java
@@ -48,6 +48,7 @@
/**
* Returns the time when the application started, in milliseconds
* elapsed since 01.01.1970.
+ * @return the time when the JVM started.
*/
public static long getStartTime() {
return JVM_START_TIME;
diff --git a/log4j-1.2-api/src/main/java/org/apache/log4j/config/PropertiesConfiguration.java b/log4j-1.2-api/src/main/java/org/apache/log4j/config/PropertiesConfiguration.java
index 2f7ac58..272367c 100644
--- a/log4j-1.2-api/src/main/java/org/apache/log4j/config/PropertiesConfiguration.java
+++ b/log4j-1.2-api/src/main/java/org/apache/log4j/config/PropertiesConfiguration.java
@@ -67,7 +67,10 @@
private final Map<String, Appender> registry;
/**
- * No argument constructor.
+ * Constructor.
+ * @param loggerContext The LoggerContext.
+ * @param source The ConfigurationSource.
+ * @param monitorIntervalSeconds The monitoring interval in seconds.
*/
public PropertiesConfiguration(final LoggerContext loggerContext, final ConfigurationSource source,
int monitorIntervalSeconds) {
diff --git a/log4j-1.2-api/src/main/java/org/apache/log4j/config/PropertySetter.java b/log4j-1.2-api/src/main/java/org/apache/log4j/config/PropertySetter.java
index 25d1d2b..b328ec3 100644
--- a/log4j-1.2-api/src/main/java/org/apache/log4j/config/PropertySetter.java
+++ b/log4j-1.2-api/src/main/java/org/apache/log4j/config/PropertySetter.java
@@ -100,13 +100,15 @@
/**
* Set the properites for the object that match the
* <code>prefix</code> passed as parameter.
+ * @param properties The properties.
+ * @param prefix The prefix of the properties to use.
*/
public void setProperties(Properties properties, String prefix) {
int len = prefix.length();
for (String key : properties.stringPropertyNames()) {
- // handle only properties that start with the desired frefix.
+ // handle only properties that start with the desired prefix.
if (key.startsWith(prefix)) {
@@ -197,6 +199,7 @@
* of the property to set.
* @param name The named of the property to set.
* @param value The value of the property.
+ * @throws PropertySetterException if no setter is available.
*/
public void setProperty(PropertyDescriptor prop, String name, String value)
throws PropertySetterException {
@@ -204,7 +207,7 @@
if (setter == null) {
throw new PropertySetterException("No setter for property [" + name + "].");
}
- Class[] paramTypes = setter.getParameterTypes();
+ Class<?>[] paramTypes = setter.getParameterTypes();
if (paramTypes.length != 1) {
throw new PropertySetterException("#params for setter != 1");
}
@@ -238,8 +241,11 @@
/**
* Convert <code>val</code> a String parameter to an object of a
* given type.
+ * @param val The value to convert.
+ * @param type The type of the value to convert to.
+ * @return The result of the conversion.
*/
- protected Object convertArg(String val, Class type) {
+ protected Object convertArg(String val, Class<?> type) {
if (val == null) {
return null;
}
diff --git a/log4j-1.2-api/src/main/java/org/apache/log4j/helpers/AppenderAttachableImpl.java b/log4j-1.2-api/src/main/java/org/apache/log4j/helpers/AppenderAttachableImpl.java
index e9e35f9..4d6aecd 100644
--- a/log4j-1.2-api/src/main/java/org/apache/log4j/helpers/AppenderAttachableImpl.java
+++ b/log4j-1.2-api/src/main/java/org/apache/log4j/helpers/AppenderAttachableImpl.java
@@ -71,6 +71,8 @@
/**
* Call the <code>doAppend</code> method on all attached appenders.
+ * @param event The event to log.
+ * @return The number of appenders.
*/
public int appendLoopOnAppenders(LoggingEvent event) {
for (Appender appender : appenders.values()) {
diff --git a/log4j-1.2-api/src/main/java/org/apache/log4j/helpers/OptionConverter.java b/log4j-1.2-api/src/main/java/org/apache/log4j/helpers/OptionConverter.java
index 5f910fa..b74a341 100644
--- a/log4j-1.2-api/src/main/java/org/apache/log4j/helpers/OptionConverter.java
+++ b/log4j-1.2-api/src/main/java/org/apache/log4j/helpers/OptionConverter.java
@@ -112,6 +112,9 @@
* returned.
*
* <p>Case of value is unimportant.
+ * @param value The value to convert.
+ * @param dEfault The default value.
+ * @return the value of the result.
*/
public static boolean toBoolean(String value, boolean dEfault) {
if (value == null) {
@@ -145,6 +148,9 @@
*
* <p> Case of <code>value</code> is insignificant for the level level, but is
* significant for the class name part, if present.
+ * @param value The value to convert.
+ * @param defaultValue The default value.
+ * @return the value of the result.
*
* @since 1.1
*/
@@ -228,6 +234,7 @@
* @param className The fully qualified class name of the object to instantiate.
* @param superClass The class to which the new object should belong.
* @param defaultValue The object to return in case of non-fulfillment
+ * @return The created object.
*/
public static Object instantiateByClassName(String className, Class<?> superClass,
Object defaultValue) {
@@ -279,9 +286,11 @@
* <code>val</code> contains a start delimeter "${" which is not
* balanced by a stop delimeter "}". </p>
*
- * <p><b>Author</b> Avy Sharell</a></p>
+ * <p><b>Author</b> Avy Sharell</p>
*
* @param val The string on which variable substitution is performed.
+ * @param props The properties to use for the substitution.
+ * @return The substituted string.
* @throws IllegalArgumentException if <code>val</code> is malformed.
*/
public static String substVars(String val, Properties props) throws IllegalArgumentException {
@@ -387,6 +396,9 @@
* Find the value corresponding to <code>key</code> in
* <code>props</code>. Then perform variable substitution on the
* found value.
+ * @param key The key used to locate the substitution string.
+ * @param props The properties to use in the substitution.
+ * @return The substituted string.
*/
public static String findAndSubst(String key, Properties props) {
String value = props.getProperty(key);
diff --git a/log4j-1.2-api/src/main/java/org/apache/log4j/rewrite/PropertyRewritePolicy.java b/log4j-1.2-api/src/main/java/org/apache/log4j/rewrite/PropertyRewritePolicy.java
index b822a99..d320d89 100644
--- a/log4j-1.2-api/src/main/java/org/apache/log4j/rewrite/PropertyRewritePolicy.java
+++ b/log4j-1.2-api/src/main/java/org/apache/log4j/rewrite/PropertyRewritePolicy.java
@@ -50,7 +50,7 @@
* <p>
* Form: propname1=propvalue1,propname2=propvalue2
*
- * @param props
+ * @param props The properties.
*/
public void setProperties(String props) {
Map hashTable = new HashMap();
diff --git a/log4j-1.2-api/src/main/java/org/apache/log4j/spi/AppenderAttachable.java b/log4j-1.2-api/src/main/java/org/apache/log4j/spi/AppenderAttachable.java
index fd464a2..120cb50 100644
--- a/log4j-1.2-api/src/main/java/org/apache/log4j/spi/AppenderAttachable.java
+++ b/log4j-1.2-api/src/main/java/org/apache/log4j/spi/AppenderAttachable.java
@@ -28,16 +28,20 @@
/**
* Add an appender.
+ * @param newAppender The Appender to add.
*/
void addAppender(Appender newAppender);
/**
* Get all previously added appenders as an Enumeration.
+ * @return The Enumeration of the Appenders.
*/
- Enumeration getAllAppenders();
+ Enumeration<Appender> getAllAppenders();
/**
* Get an appender by name.
+ * @param name The name of the Appender.
+ * @return The Appender.
*/
Appender getAppender(String name);
@@ -45,6 +49,8 @@
/**
* Returns <code>true</code> if the specified appender is in list of
* attached attached, <code>false</code> otherwise.
+ * @param appender The Appender to check.
+ * @return true if the Appender is attached.
*
* @since 1.2
*/
@@ -58,6 +64,7 @@
/**
* Remove the appender passed as parameter from the list of appenders.
+ * @param appender The Appender to remove.
*/
void removeAppender(Appender appender);
@@ -65,6 +72,7 @@
/**
* Remove the appender with the name passed as parameter from the
* list of appenders.
+ * @param name The name of the Appender to remove.
*/
void removeAppender(String name);
}
diff --git a/log4j-1.2-api/src/main/java/org/apache/log4j/spi/LoggingEvent.java b/log4j-1.2-api/src/main/java/org/apache/log4j/spi/LoggingEvent.java
index d7755a2..8d26d26 100644
--- a/log4j-1.2-api/src/main/java/org/apache/log4j/spi/LoggingEvent.java
+++ b/log4j-1.2-api/src/main/java/org/apache/log4j/spi/LoggingEvent.java
@@ -32,6 +32,7 @@
/**
Set the location information for this logging event. The collected
information is cached for future use.
+ @return Always returns null.
*/
public LocationInfo getLocationInformation() {
return null;
@@ -39,7 +40,9 @@
/**
* Return the level of this event. Use this form instead of directly
- * accessing the <code>level</code> field. */
+ * accessing the <code>level</code> field.
+ * @return Always returns null.
+ */
public Level getLevel() {
return null;
}
@@ -47,6 +50,7 @@
/**
* Return the name of the logger. Use this form instead of directly
* accessing the <code>categoryName</code> field.
+ * @return Always returns null.
*/
public String getLoggerName() {
return null;
@@ -63,6 +67,7 @@
/**
* Gets the logger of the event.
* Use should be restricted to cloning events.
+ * @return Always returns null.
* @since 1.2.15
*/
public Category getLogger() {
@@ -76,7 +81,7 @@
passed by the user to generate the logging event. After
serialization, the returned value equals the String form of the
message possibly after object rendering.
-
+ @return Always returns null.
@since 1.1 */
public
Object getMessage() {
@@ -97,24 +102,23 @@
Obtain a copy of this thread's MDC prior to serialization or
asynchronous logging.
*/
- public
- void getMDCCopy() {
+ public void getMDCCopy() {
}
- public
- String getRenderedMessage() {
+ public String getRenderedMessage() {
return null;
}
/**
Returns the time when the application started, in milliseconds
- elapsed since 01.01.1970. */
+ elapsed since 01.01.1970.
+ @return the JVM start time.
+ */
public static long getStartTime() {
return LogEventAdapter.getStartTime();
}
- public
- String getThreadName() {
+ public String getThreadName() {
return null;
}
@@ -124,18 +128,17 @@
<p>Note that the {@link Throwable} object contained within a
{@link ThrowableInformation} does not survive serialization.
-
+ @return Always returns null.
@since 1.1 */
- public
- ThrowableInformation getThrowableInformation() {
+ public ThrowableInformation getThrowableInformation() {
return null;
}
/**
Return this event's throwable's string[] representaion.
+ @return Always returns null.
*/
- public
- String[] getThrowableStrRep() {
+ public String[] getThrowableStrRep() {
return null;
}
diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/Logger.java b/log4j-api/src/main/java/org/apache/logging/log4j/Logger.java
index 37e25a6..b0b78e6 100644
--- a/log4j-api/src/main/java/org/apache/logging/log4j/Logger.java
+++ b/log4j-api/src/main/java/org/apache/logging/log4j/Logger.java
@@ -32,12 +32,12 @@
* {@link LogManager#getLogger()} method). Thus, the simplest way to use this would be like so:
* </p>
*
- * <pre>
+ * <pre><code>
* public class MyClass {
* private static final Logger LOGGER = LogManager.getLogger();
* // ...
* }
- * </pre>
+ * </code></pre>
* <p>
* For ease of filtering, searching, sorting, etc., it is generally a good idea to create Loggers for each class rather
* than sharing Loggers. Instead, {@link Marker Markers} should be used for shared, filterable identification.
@@ -51,13 +51,13 @@
* allow client code to lazily log messages without explicitly checking if the requested log level is enabled. For
* example, previously one would write:
*
- * <pre>
+ * <pre><code>
* // pre-Java 8 style optimization: explicitly check the log level
* // to make sure the expensiveOperation() method is only called if necessary
* if (logger.isTraceEnabled()) {
* logger.trace("Some long-running operation returned {}", expensiveOperation());
* }
- * </pre>
+ * </code></pre>
* <p>
* With Java 8, the same effect can be achieved with a lambda expression:
*
@@ -68,7 +68,7 @@
* </pre>
*
* <p>
- * Note that although {@link MessageSupplier} is provided, using {@link Supplier Supplier<Message>} works just the
+ * Note that although {@link MessageSupplier} is provided, using {@link Supplier {@code Supplier<Message>}} works just the
* same. MessageSupplier was deprecated in 2.6 and un-deprecated in 2.8.1. Anonymous class usage of these APIs
* should prefer using Supplier instead.
* </p>
@@ -3495,20 +3495,20 @@
/**
* Logs entry to a method along with its parameters. For example,
*
- * <pre>
+ * <pre><code>
* public void doSomething(String foo, int bar) {
* LOGGER.traceEntry("Parameters: {} and {}", foo, bar);
* // do something
* }
- * </pre>
+ * </code></pre>
* or:
- * <pre>
+ * <pre><code>
* public int doSomething(String foo, int bar) {
* Message m = LOGGER.traceEntry("doSomething(foo={}, bar={})", foo, bar);
* // do something
* return traceExit(m, value);
* }
- * </pre>
+ * </code></pre>
*
* @param format The format String for the parameters.
* @param params The parameters to the method.
@@ -3522,10 +3522,12 @@
* Logs entry to a method along with its parameters. For example,
*
* <pre>
+ * <code>
* public void doSomething(Request foo) {
* LOGGER.traceEntry(()->gson.toJson(foo));
* // do something
* }
+ * </code>
* </pre>
*
* @param paramSuppliers The Suppliers for the parameters to the method.
@@ -3539,10 +3541,12 @@
* Logs entry to a method along with its parameters. For example,
*
* <pre>
+ * <code>
* public void doSomething(String foo, int bar) {
* LOGGER.traceEntry("Parameters: {} and {}", ()->gson.toJson(foo), ()-> bar);
* // do something
* }
+ * </code>
* </pre>
*
* @param format The format String for the parameters.
@@ -3555,12 +3559,12 @@
/**
* Logs entry to a method using a Message to describe the parameters.
- * <pre>
+ * <pre><code>
* public void doSomething(Request foo) {
* LOGGER.traceEntry(new JsonMessage(foo));
* // do something
* }
- * </pre>
+ * </code></pre>
* <p>
* Avoid passing a {@code ReusableMessage} to this method (therefore, also avoid passing messages created by
* calling {@code logger.getMessageFactory().newMessage("some message")}): Log4j will replace such messages with
@@ -3586,9 +3590,9 @@
/**
* Logs exiting from a method with the result. This may be coded as:
*
- * <pre>
+ * <pre><code>
* return LOGGER.traceExit(myResult);
- * </pre>
+ * </code></pre>
*
* @param <R> The type of the parameter and object being returned.
* @param result The result being returned from the method call.
@@ -3601,9 +3605,9 @@
/**
* Logs exiting from a method with the result. This may be coded as:
*
- * <pre>
+ * <pre><code>
* return LOGGER.traceExit("Result: {}", myResult);
- * </pre>
+ * </code></pre>
*
* @param <R> The type of the parameter and object being returned.
* @param format The format String for the result.
@@ -3617,13 +3621,13 @@
/**
* Logs exiting from a method with no result. Allows custom formatting of the result. This may be coded as:
*
- * <pre>
+ * <pre><code>
* public long doSomething(int a, int b) {
* EntryMessage m = traceEntry("doSomething(a={}, b={})", a, b);
* // ...
* return LOGGER.traceExit(m);
* }
- * </pre>
+ * </code></pre>
* @param message The Message containing the formatted result.
*
* @since 2.6
@@ -3633,13 +3637,13 @@
/**
* Logs exiting from a method with the result. Allows custom formatting of the result. This may be coded as:
*
- * <pre>
+ * <pre><code>
* public long doSomething(int a, int b) {
* EntryMessage m = traceEntry("doSomething(a={}, b={})", a, b);
* // ...
* return LOGGER.traceExit(m, myResult);
* }
- * </pre>
+ * </code></pre>
* @param message The Message containing the formatted result.
* @param result The result being returned from the method call.
*
@@ -3653,9 +3657,9 @@
/**
* Logs exiting from a method with the result. Allows custom formatting of the result. This may be coded as:
*
- * <pre>
+ * <pre><code>
* return LOGGER.traceExit(new JsonMessage(myResult), myResult);
- * </pre>
+ * </code></pre>
* @param message The Message containing the formatted result.
* @param result The result being returned from the method call.
*
