Update JavaDoc for logging and marshalling

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1874965 13f79535-47bb-0310-9956-ffa450edef68

4 files changed, 34 insertions, 25 deletions

diff --git a/src/java/org/apache/poi/util/CommonsLogger.java b/src/java/org/apache/poi/util/CommonsLogger.java
index c5a4374fc8..cdc4f92804 100644
--- a/src/java/org/apache/poi/util/CommonsLogger.java
+++ b/src/java/org/apache/poi/util/CommonsLogger.java
@@ -1,4 +1,3 @@
-
 /* ====================================================================
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
@@ -15,18 +14,16 @@
    See the License for the specific language governing permissions and
    limitations under the License.
 ==================================================================== */
-        
-
 package org.apache.poi.util;
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 
 /**
- * A logger class that strives to make it as easy as possible for
- * developers to write log calls, while simultaneously making those
- * calls as cheap as possible by performing lazy evaluation of the log
- * message.<p>
+ * An implementation of the {@link POILogger} using the
+ * Apache Commons Logging framework. Which itself can be configured to
+ * send log to various different log frameworks and even allows to create
+ * a small wrapper for custom log frameworks.
  */
 public class CommonsLogger implements POILogger
 {
@@ -36,8 +33,8 @@ public class CommonsLogger implements POILogger
     @Override
     public void initialize(final String cat) {
         this.log = _creator.getInstance(cat);
-    }   
-     
+    }
+
     /**
      * Log a message
      *
@@ -81,7 +78,7 @@ public class CommonsLogger implements POILogger
                 break;
         }
     }
-    
+
     /**
      * Log a message
      *
diff --git a/src/java/org/apache/poi/util/NullLogger.java b/src/java/org/apache/poi/util/NullLogger.java
index e4fab3903b..8a9daeaa0b 100644
--- a/src/java/org/apache/poi/util/NullLogger.java
+++ b/src/java/org/apache/poi/util/NullLogger.java
@@ -18,10 +18,11 @@
 package org.apache.poi.util;
 
 /**
- * A logger class that strives to make it as easy as possible for
- * developers to write log calls, while simultaneously making those
- * calls as cheap as possible by performing lazy evaluation of the log
- * message.<p>
+ * An empty-implementation of the {@link POILogger}.
+ *
+ * This can be used to not log anything, however the suggested approach
+ * in production systems is to use the {@link CommonsLogger} and configure
+ * proper log-handling via Apache Commons Logging.
  */
 @Internal
 public class NullLogger implements POILogger {
@@ -66,7 +67,7 @@ public class NullLogger implements POILogger {
         // do nothing
     }
 
-    
+
     /**
      * Check if a logger is enabled to log at the specified level
      *
diff --git a/src/java/org/apache/poi/util/POILogger.java b/src/java/org/apache/poi/util/POILogger.java
index 627f83743e..fa52baabd5 100644
--- a/src/java/org/apache/poi/util/POILogger.java
+++ b/src/java/org/apache/poi/util/POILogger.java
@@ -22,6 +22,19 @@ package org.apache.poi.util;
  * developers to write log calls, while simultaneously making those
  * calls as cheap as possible by performing lazy evaluation of the log
  * message.
+ *
+ * A logger can be selected via system properties, e.g.
+ * <code>
+ *     -Dorg.apache.poi.util.POILogger=org.apache.poi.util.SystemOutLogger
+ * </code>
+ *
+ * The following Logger-implementations are provided:
+ *
+ * <ul>
+ *     <li>NullLogger</li>
+ *     <li>CommonsLogger</li>
+ *     <li>SystemOutLogger</li>
+ * </ul>
  */
 @Internal
 public interface POILogger {
@@ -62,7 +75,7 @@ public interface POILogger {
      * Check if a logger is enabled to log at the specified level
      * This allows code to avoid building strings or evaluating functions in
      * the arguments to log.
-     * 
+     *
      * An example:
      * <code><pre>
      * if (logger.check(POILogger.INFO)) {
@@ -92,11 +105,11 @@ public interface POILogger {
                 sb.append(objs[i]);
             }
         }
-        
+
         String msg = sb.toString();
         // log forging escape
         msg = msg.replaceAll("[\r\n]+", " ");
-        
+
         if (lastEx == null) {
             _log(level, msg);
         } else {
diff --git a/src/java/org/apache/poi/util/SystemOutLogger.java b/src/java/org/apache/poi/util/SystemOutLogger.java
index 8eba4b0063..3567c40808 100644
--- a/src/java/org/apache/poi/util/SystemOutLogger.java
+++ b/src/java/org/apache/poi/util/SystemOutLogger.java
@@ -14,16 +14,14 @@
    See the License for the specific language governing permissions and
    limitations under the License.
 ==================================================================== */
-
 package org.apache.poi.util;
 
-
-
 /**
- * A logger class that strives to make it as easy as possible for
- * developers to write log calls, while simultaneously making those
- * calls as cheap as possible by performing lazy evaluation of the log
- * message.
+ * An implementation of the {@link POILogger} which uses System.out.println.
+ *
+ * This can be used to provide simply output from applications, however the
+ * suggested approach in production systems is to use the {@link CommonsLogger}
+ * and configure proper log-handling via Apache Commons Logging.
  */
 public class SystemOutLogger implements POILogger {
     /**