Improved javadocs, started to add Marker specific log statements to the Logger interface

build.xml

@@ -5,7 +5,7 @@
   <property file="build.properties"/>
 
   <!-- The directory where source files are stored. -->
-  <property name="version" value="1.0-beta4"/>
+  <property name="version" value="1.0-beta5"/>
 
   <property name="tmp.java.source.dir" value="./tmp/src"/>
   <property name="tmp.javac.dest" value="./tmp/classes"/>
@@ -144,11 +144,19 @@
     <copy todir="tmp/src">
       <fileset dir="src/filtered-java">
         <include name="**/*.java"/>
-        <include name="**/package.html"/>
       </fileset>
       <filterset><filter token="IMPL" value="NOP"/></filterset>
+      <filterset><filter token="MARKER_FACTORY_IMPL_PREFIX" 
+                         value="Basic"/>
+      </filterset>
     </copy>
 
+    <copy todir="tmp/src">
+      <fileset dir="src/java">
+        <include name="**/*.java"/>
+        <include name="**/*.html"/>
+      </fileset>
+    </copy>
 
     <mkdir dir="${javadoc.dest}" />
     

src/filtered-java/org/slf4j/LoggerFactory.java

@@ -37,16 +37,27 @@ package org.slf4j;
 // WARNING
 
 /**
- * The <code>LoggerFactory</code> can produce Loggers for various logging APIs,
- * most notably for log4j, JDK 1.4 logging. Other implemenations such as
- * {@link org.slf4j.impl.NOPLogger NOPLogger} and
+ * The <code>LoggerFactory</code> is a utility class producing Loggers 
+ * for various logging APIs, most notably for NLOG4J and JDK 1.4 logging. 
+ * Other implemenations such as {@link org.slf4j.impl.NOPLogger NOPLogger} and
  * {@link org.slf4j.impl.SimpleLogger SimpleLogger} are also supported.
  *
+ * <p><code>LoggerFactory</code> is essentially a wrapper around an 
+ * {@link ILoggerFactory} instance bound with <code>LoggerFactory</code> 
+ * at compile time.
+ * 
+ * <p>Please note that all methods in <code>LoggerFactory</code> are 
+ * static.
+ * 
  * @author Ceki G&uuml;lc&uuml;
  */
-public class LoggerFactory {
+public final class LoggerFactory {
   static ILoggerFactory loggerFactory;
 
+  // private constructor prevents instantiation
+  private LoggerFactory() {
+  }
+  
   // 
   // WARNING Do not modify copies but the original in
   //         $SLF4J_HOME/src/filtered-java/org/slf4j/
@@ -74,7 +85,7 @@ public class LoggerFactory {
   }
 
   /**
-   * Fetch the appropriate adapter as intructed by the system propties.
+   * Fetch the appropriate ILoggerFactory as intructed by the system propties.
    * 
    * @return The appropriate ILoggerFactory instance as directed from the 
    * system properties
@@ -114,7 +125,8 @@ public class LoggerFactory {
 
   /**
    * Return a logger named according to the name parameter using the 
-   * previously bound  {@link LoggerFactoryAdapter adapter}.
+   * statically bound  {@link ILoggerFactory} instance.
+   * 
    * @param name The name of the logger.
    * @return logger
    */
@@ -122,6 +134,13 @@ public class LoggerFactory {
     return loggerFactory.getLogger(name);
   }
 
+  /**
+   * Return a logger named corresponding to the class passed as parameter,
+   * using the statically bound  {@link ILoggerFactory} instance.
+   * 
+   * @param clazz the returned logger will be named after clazz 
+   * @return logger
+   */
   public static Logger getLogger(Class clazz) {
     return loggerFactory.getLogger(clazz.getName());
   }

src/filtered-java/org/slf4j/MarkerFactory.java

@@ -38,14 +38,22 @@ package org.slf4j;
 
 
 /**
- * A static MarkerFactory bound to a specific {@link IMarkerFactory} instance at
- * at compile time. 
+ * MarkerFactory is a utility class producing Marker instances as appropriate 
+ * for each logging systems.
+ * 
+ * MarkerFactory is essentially a wrapper around an IMarkerFactory instance 
+ * bound with the MarkerFactory class at compile time. 
+ * 
+ * Please note that all methods in MarkerFactory are static.
  * 
  * @author Ceki Gulcu
  */
 public class MarkerFactory {
   static IMarkerFactory markerFactory;
 
+  private MarkerFactory() {      
+  }
+  
   // 
   // WARNING Do not modify copies but the original at
   //         $SLF4J_HOME/src/filtered-java/org/slf4j/
@@ -59,14 +67,14 @@ public class MarkerFactory {
        Util.reportFailure(
            "Could not instantiate instance of class [" + markerFactoryClassStr + "]",
            e);
-     }
-      
+     }      
   }
   
   /**
    * Return a Marker instnace as specified by the name parameter using the 
-   * previously bound  {@link IMakerFactory marker factory instance}.
-   * @param name The name of the Marker.
+   * previously bound  {@link IMarkerFactory} instance.
+   * 
+   * @param name The name of the {@link Marker} object to return. 
    * @return marker
    */
   public static Marker getMarker(String name) {

src/java/org/slf4j/ILoggerFactory.java

@@ -34,6 +34,9 @@ package org.slf4j;
 
 
 /**
+ * Implementaitons of this interface are used to manufacture {@link Logger} 
+ * instances.
+ * 
  * ILoggerFactory interface is used internally by {@link
  * LoggerFactory}.
  * 

src/java/org/slf4j/Logger.java

@@ -56,6 +56,14 @@ public interface Logger {
    */
   public void debug(String msg);
   
+
+  /**
+   * Log a message with the specific Marker at the DEBUG level.
+   * 
+   * @param marker The marker specific for this log statement
+   * @param msg the message string to be logged
+   */
+  public void debug(Marker marker, String msg);
   
   /**
    * Log a message at the DEBUG level according to the specified format

src/java/org/slf4j/Marker.java

@@ -35,13 +35,47 @@ package org.slf4j;
 
 import java.util.Iterator;
 
+/**
+ * Markers are named objects which can be used to enrich log statements. 
+ * 
+ * <p>Markers can contain child markers which can contain children of their
+ * own.
+ * 
+ * @author Ceki Gulcu
+ */
 public interface Marker {
  
+  /**
+   * Get the name of this Marker.
+   * @return name of marker
+   */ 
   public String getName();
 
+  /**
+   * Add a child Marker to this Marker.
+   * @param child a child marker
+   */
   public void add(Marker child);
+  
+  /**
+   * Remove a child Marker.
+   * @param child the child Marker to remove
+   * @return true if child could be found and removed, false otherwise.
+   */
   public boolean remove(Marker child);
+  
+  /**
+   * Does this marker have children?
+   * @return true if this marker has children, false otherwise.
+   */
   public boolean hasChildren();
+  
+  /**
+   * Returns an Iterator which can be used to iterator over the children of this 
+   * marker. An empty iterator is returned when this marker has no children.
+   * 
+   * @return Iterator over the children of this marker
+   */
   public Iterator iterator();
   
 //  void makeImmutable();

tests/build.xml

@@ -27,15 +27,15 @@
     <pathelement location="../slf4j-simple.jar"/>
   </path>
 
-   <path id="jdk14.classpath">
+  <path id="jdk14.classpath">
     <path refid="basic.classpath"/>
     <pathelement location="../slf4j-jdk14.jar"/>
   </path>
 
-   <path id="nlog4j1212.classpath">
+   <path id="nlog4j12x.classpath">
      <path refid="basic.classpath"/>
-     <fileset dir="lib">
-       <include name="nlog4j-1.2.12.jar"/>
+     <fileset dir="./lib/">
+       <include name="nlog4j*.jar"/>
      </fileset>
   </path>
 
@@ -107,7 +107,7 @@
                                      InvokeNOP,
                                      InvokeSimple,
                                      InvokeJDK14,
-                                     InvokeNLOG4J1212"
+                                     InvokeNLOG4J12x"
                                      />
 
   <target name="MessageFormatter" depends="build, cleanOutputDir">
@@ -143,10 +143,10 @@
   </target>
 
 
-  <target name="InvokeNLOG4J1212" depends="build, cleanOutputDir">
-    <copy file="input/nlog4j1212/basic.xml" tofile="${tests.javac.dest}/log4j.xml"/>
+  <target name="InvokeNLOG4J12x" depends="build, cleanOutputDir">
+    <copy file="input/nlog4j12x/basic.xml" tofile="${tests.javac.dest}/log4j.xml"/>
     <junit printsummary="yes" fork="yes" haltonfailure="yes">
-      <classpath refid="nlog4j1212.classpath"/>
+      <classpath refid="nlog4j12x.classpath"/>
       <formatter type="plain" usefile="false"/>
       <test name="org.slf4j.InvokingSLF4J" />
     </junit>