improved javadocs

jcl-over-slf4j/src/main/java/org/apache/commons/logging/Log.java

@@ -102,6 +102,8 @@ public interface Log {
      * <p> Call this method to prevent having to perform expensive operations
      * (for example, <code>String</code> concatenation)
      * when the log level is more than info. </p>
+     * 
+     * @return true if info enabled, false otherwise
      */
     public boolean isInfoEnabled();
 
@@ -112,6 +114,8 @@ public interface Log {
      * <p> Call this method to prevent having to perform expensive operations
      * (for example, <code>String</code> concatenation)
      * when the log level is more than trace. </p>
+     * 
+     * @return true if trace enabled, false otherwise
      */
     public boolean isTraceEnabled();
 

jcl-over-slf4j/src/main/java/org/apache/commons/logging/LogFactory.java

@@ -140,15 +140,17 @@ protected LogFactory() {
    * Return the configuration attribute with the specified name (if any), or
    * <code>null</code> if there is no such attribute.
    * 
-   * @param name
-   *                Name of the attribute to return
+   * @param name Name of the attribute to return
+   * @return configuration attribute
    */
   public abstract Object getAttribute(String name);
 
   /**
    * Return an array containing the names of all currently defined configuration
    * attributes. If there are no such attributes, a zero length array is
    * returned.
+   * 
+   * @return names of all currently defined configuration attributes
    */
   public abstract String[] getAttributeNames();
 

jul-to-slf4j/src/main/java/org/slf4j/bridge/SLF4JBridgeHandler.java

@@ -146,7 +146,7 @@ public static void uninstall() throws SecurityException {
   /**
    * Returns true if SLF4JBridgeHandler has been previously installed, returns false otherwise.
    *
-   * @return
+   * @return true if SLF4JBridgeHandler is already installed, false other wise
    * @throws SecurityException
    */
   public static boolean isInstalled() throws SecurityException {

pom.xml

@@ -216,14 +216,14 @@
                 <linkJavadoc>true</linkJavadoc>
               </configuration>
             </plugin>
+
             <plugin>
               <groupId>org.apache.maven.plugins</groupId>
               <artifactId>maven-javadoc-plugin</artifactId>
               <version>2.8</version>
               <configuration>
-                <aggregate>true</aggregate>
-                <excludePackageNames>org.slf4j.migrator:org.slf4j.migrator.*
-                </excludePackageNames>
+                <!--<aggregate>true</aggregate>-->
+                <excludePackageNames>org.slf4j.migrator:org.slf4j.migrator.*</excludePackageNames>
                 <links>
                   <link>
                     http://java.sun.com/j2se/1.5.0/docs/api
@@ -238,7 +238,7 @@
                   <group>
                     <title>SLF4J extensions</title>
                     <packages>
-                      org.slf4j.profiler:org.slf4j.ext:org.slf4j.instrumentation:org.slf4j.agent
+                      org.slf4j.cal10n:org.slf4j.profiler:org.slf4j.ext:org.slf4j.instrumentation:org.slf4j.agent
                     </packages>
                   </group>
 
@@ -248,15 +248,17 @@
                   </group>
 
                   <group>
-                    <title>Apache log4j</title>
-                    <packages>org.apache.log4j</packages>
+                    <title>java.util.logging (JUL) to SLF4J bridge</title>
+                    <packages>org.slf4j.bridge</packages>
                   </group>
 
                   <group>
-                    <title>java.util.logging (JUL) to SLF4J bridge</title>
-                    <packages>org.slf4j.bridge</packages>
+                    <title>Apache log4j</title>
+                    <packages>org.apache.log4j:org.apache.log4j.*</packages>
                   </group>
 
+
+
                 </groups>
               </configuration>
             </plugin>
@@ -275,53 +277,6 @@
         <maven.test.skip>true</maven.test.skip>
       </properties>
     </profile>
-    <profile>
-      <id>osgi</id>
-      <modules>
-        <module>osgi-over-slf4j</module>
-        <module>slf4j-osgi-test-bundle</module>
-        <module>slf4j-osgi-integration-test</module>
-      </modules>
-
-      <repositories>
-        <repository>
-          <id>m2apache.snapshots</id>
-          <url>http://people.apache.org/repo/m2-snapshot-repository</url>
-          <releases>
-            <enabled>false</enabled>
-          </releases>
-          <snapshots>
-            <enabled>true</enabled>
-          </snapshots>
-        </repository>
-
-        <repository>
-          <id>springframework.org</id>
-          <name>Springframework Maven SNAPSHOT Repository</name>
-          <url>http://static.springframework.org/maven2-snapshots/</url>
-          <snapshots>
-            <enabled>true</enabled>
-          </snapshots>
-        </repository>
-
-      </repositories>
-
-      <pluginRepositories>
-        <pluginRepository>
-          <id>apache.snapshots</id>
-          <name>Apache Snapshot Plugin Repository</name>
-          <url>http://people.apache.org/repo/m2-snapshot-repository</url>
-          <releases>
-            <enabled>false</enabled>
-          </releases>
-          <snapshots>
-            <enabled>true</enabled>
-          </snapshots>
-        </pluginRepository>
-      </pluginRepositories>
-
-    </profile>
-
 
     <profile>
       <id>javadocjar</id>

slf4j-api/src/main/java/org/slf4j/ILoggerFactory.java

@@ -52,6 +52,7 @@ public interface ILoggerFactory {
    * return the same logger instance regardless of the requested name.
    * 
    * @param name the name of the Logger to return
+   * @return a Logger instance 
    */
   public Logger getLogger(String name);
 }

slf4j-api/src/main/java/org/slf4j/IMarkerFactory.java

@@ -53,7 +53,8 @@ public interface IMarkerFactory {
   /**
    * Checks if the marker with the name already exists. If name is null, then false 
    * is returned.
-   * 
+   *  
+   * @param name logger name to check for
    * @return true id the marker exists, false otherwise. 
    */
   boolean exists(String name);
@@ -73,7 +74,8 @@ public interface IMarkerFactory {
 
   /**
    * Create a marker which is detached (even at birth) from this IMarkerFactory.
-   *
+   * 
+   * @param name marker name
    * @return a dangling marker
    * @since 1.5.1
    */

slf4j-api/src/main/java/org/slf4j/Logger.java

@@ -52,6 +52,13 @@
  * }
  * </pre>
  *
+ * Be sure to read the FAQ entry relating to <a href="../../../faq.html#logging_performance">parameterized
+ * logging</a>. Note that logging statements can be parameterized in
+ * <a href="../../../faq.html#paramException">presence of an exception/throwable</a>.
+ *
+ * <p>Once you are comfortable using loggers, i.e. instances of this interface, consider using
+ * <a href="MDC.html">MDC</a> as well as <a href="Marker.html">Markers</a>.</p>
+ *
  * @author Ceki G&uuml;lc&uuml;
  */
 public interface Logger {
@@ -66,6 +73,7 @@ public interface Logger {
 
   /**
    * Return the name of this <code>Logger</code> instance.
+   * @return name of this logger instance 
    */
   public String getName();
 
@@ -148,6 +156,9 @@ public interface Logger {
    * marker data is also taken into account.
    *
    * @param marker The marker data to take into consideration
+   * @return True if this Logger is enabled for the TRACE level,
+   *         false otherwise.
+   *         
    * @since 1.4
    */
   public boolean isTraceEnabled(Marker marker);
@@ -285,6 +296,8 @@ public interface Logger {
    * marker data is also taken into account.
    *
    * @param marker The marker data to take into consideration
+   * @return True if this Logger is enabled for the DEBUG level,
+   *         false otherwise. 
    */
   public boolean isDebugEnabled(Marker marker);
 
@@ -415,6 +428,7 @@ public interface Logger {
    * data is also taken into consideration.
    *
    * @param marker The marker data to take into consideration
+   * @return true if this logger is warn enabled, false otherwise 
    */
   public boolean isInfoEnabled(Marker marker);
 
@@ -544,6 +558,8 @@ public interface Logger {
    * data is also taken into consideration.
    *
    * @param marker The marker data to take into consideration
+   * @return True if this Logger is enabled for the WARN level,
+   *         false otherwise.
    */
   public boolean isWarnEnabled(Marker marker);
 
@@ -671,6 +687,8 @@ public interface Logger {
    * marker data is also taken into consideration.
    *
    * @param marker The marker data to take into consideration
+   * @return True if this Logger is enabled for the ERROR level,
+   *         false otherwise.
    */
   public boolean isErrorEnabled(Marker marker);
 

slf4j-api/src/main/java/org/slf4j/MDC.java

@@ -45,7 +45,7 @@
  * and slf4j-nop, {@link NOPMDCAdapter} will be used.
  *
  * <p>
- * Thus, as a SLF4J user, you can take advantage of MDC in the presence of log4j
+ * Thus, as a SLF4J user, you can take advantage of MDC in the presence of log4j,
  * logback, or java.util.logging, but without forcing these systems as
  * dependencies upon your users.
  * 
@@ -90,13 +90,16 @@ private MDC() {
   }
 
   /**
-   * Put a context value (the <code>val</code> parameter) as identified with the
-   * <code>key</code> parameter into the current thread's context map. The
+   * Put a diagnostic context value (the <code>val</code> parameter) as identified with the
+   * <code>key</code> parameter into the current thread's diagnostic context map. The
    * <code>key</code> parameter cannot be null. The <code>val</code> parameter
    * can be null only if the underlying implementation supports it.
    * 
    * <p>
    * This method delegates all work to the MDC of the underlying logging system.
+   *
+   * @param key non-null key 
+   * @param val value to put in the map
    * 
    * @throws IllegalArgumentException
    *           in case the "key" parameter is null
@@ -114,12 +117,13 @@ public static void put(String key, String val)
   }
 
   /**
-   * Get the context identified by the <code>key</code> parameter. The
+   * Get the diagnostic context identified by the <code>key</code> parameter. The
    * <code>key</code> parameter cannot be null.
    * 
    * <p>
    * This method delegates all work to the MDC of the underlying logging system.
-   * 
+   *
+   * @param key  
    * @return the string value identified by the <code>key</code> parameter.
    * @throws IllegalArgumentException
    *           in case the "key" parameter is null
@@ -137,11 +141,12 @@ public static String get(String key) throws IllegalArgumentException {
   }
 
   /**
-   * Remove the the context identified by the <code>key</code> parameter using
+   * Remove the diagnostic context identified by the <code>key</code> parameter using
    * the underlying system's MDC implementation. The <code>key</code> parameter
    * cannot be null. This method does nothing if there is no previous value
    * associated with <code>key</code>.
-   * 
+   *
+   * @param key  
    * @throws IllegalArgumentException
    *           in case the "key" parameter is null
    */

slf4j-api/src/main/java/org/slf4j/Marker.java

@@ -115,8 +115,7 @@ public interface Marker extends Serializable {
    * 
    * If 'name' is null the returned value is always false.
    * 
-   * @param other
-   *                The marker to test for inclusion.
+   * @param name The marker name to test for inclusion.
    * @return Whether this marker contains the other marker.
    */
   public boolean contains(String name);

slf4j-api/src/main/java/org/slf4j/MarkerFactory.java

@@ -74,6 +74,7 @@ public static Marker getMarker(String name) {
   /**
    * Create a marker which is detached (even at birth) from the MarkerFactory.
    *
+   * @param name the name of the marker
    * @return a dangling marker
    * @since 1.5.1
    */

slf4j-api/src/main/java/org/slf4j/helpers/NOPLogger.java

@@ -80,7 +80,7 @@ public final void trace(String format, Object arg1, Object arg2) {
   }
 
   /** A NOP implementation.  */
-  public final void trace(String format, Object[] argArray) {
+  public final void trace(String format, Object... argArray) {
     // NOP
   }
 
@@ -113,7 +113,7 @@ public final void debug(String format, Object arg1, Object arg2) {
   }
 
   /** A NOP implementation.  */
-  public final void debug(String format, Object[] argArray) {
+  public final void debug(String format, Object... argArray) {
     // NOP
   }
 
@@ -150,7 +150,7 @@ final public void info(String format, Object arg1, Object arg2) {
   }
 
   /** A NOP implementation.  */
-  public final void info(String format, Object[] argArray) {
+  public final void info(String format, Object... argArray) {
     // NOP
   }
 
@@ -185,7 +185,7 @@ final public void warn(String format, Object arg1, Object arg2) {
   }
 
   /** A NOP implementation.  */
-  public final void warn(String format, Object[] argArray) {
+  public final void warn(String format, Object... argArray) {
     // NOP
   }
 
@@ -217,7 +217,7 @@ final public void error(String format, Object arg1, Object arg2) {
   }
 
   /** A NOP implementation.  */
-  public final void error(String format, Object[] argArray) {
+  public final void error(String format, Object... argArray) {
     // NOP
   }
 

slf4j-ext/src/main/java/org/slf4j/cal10n/LocLoggerFactory.java

@@ -56,7 +56,7 @@ public LocLoggerFactory(IMessageConveyor imc) {
    * Get an LocLogger instance by name.
    * 
    * @param name
-   * @return
+   * @return LocLogger instance by name.
    */
   public LocLogger getLocLogger(String name) {
     return new LocLogger(LoggerFactory.getLogger(name), imc);
@@ -67,9 +67,8 @@ public LocLogger getLocLogger(String name) {
    * after the class.
    * 
    * @param clazz
-   * @return
+   * @return LocLogger instance by class
    */
-  @SuppressWarnings("unchecked")
   public LocLogger getLocLogger(Class clazz) {
     return getLocLogger(clazz.getName());
   }

slf4j-ext/src/main/java/org/slf4j/cal10n/package.html

@@ -0,0 +1,12 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+
+<html>
+  <head>
+    <title></title>
+  </head>
+
+
+  <body>
+    <p>SLF4J API extensions</p>
+  </body>
+</html>