From 909846c6b1a92ddcc1ecadfdb5d57bc4855b41d1 Mon Sep 17 00:00:00 2001
From: nordligulv <nordligulv@gmail.com>
Date: Wed, 27 Mar 2013 21:37:47 +0400
Subject: [PATCH] update slf4j android docs

---
 .../org/slf4j/impl/AndroidLoggerAdapter.java  | 40 ++++++++++++++++---
 .../org/slf4j/impl/AndroidLoggerFactory.java  | 22 +++++-----
 2 files changed, 47 insertions(+), 15 deletions(-)

diff --git a/slf4j-android/src/main/java/org/slf4j/impl/AndroidLoggerAdapter.java b/slf4j-android/src/main/java/org/slf4j/impl/AndroidLoggerAdapter.java
index e88cfc89..9472aaa2 100755
--- a/slf4j-android/src/main/java/org/slf4j/impl/AndroidLoggerAdapter.java
+++ b/slf4j-android/src/main/java/org/slf4j/impl/AndroidLoggerAdapter.java
@@ -30,15 +30,15 @@ import org.slf4j.helpers.MarkerIgnoringBase;
 import org.slf4j.helpers.MessageFormatter;
 
 /**
- * A simple implementation that delegates all log requests to the Google Android
+ * <p>A simple implementation that delegates all log requests to the Google Android
  * logging facilities. Note that this logger does not support {@link org.slf4j.Marker}.
  * Methods taking marker data as parameter simply invoke the eponymous method
- * without the Marker argument, discarding any marker data in the process.
- * <p/>
- * The logging levels specified for SLF4J can be almost directly mapped to
+ * without the Marker argument, discarding any marker data in the process.</p>
+ *
+ * <p>The logging levels specified for SLF4J can be almost directly mapped to
  * the levels that exist in the Google Android platform. The following table
- * shows the mapping implemented by this logger.
- * <p/>
+ * shows the mapping implemented by this logger.</p>
+ *
  * <table border="1">
  * <tr><th><b>SLF4J<b></th><th><b>Android</b></th></tr>
  * <tr><td>TRACE</td><td>{@link android.util.Log#VERBOSE}</td></tr>
@@ -48,6 +48,34 @@ import org.slf4j.helpers.MessageFormatter;
  * <tr><td>ERROR</td><td>{@link android.util.Log#ERROR}</td></tr>
  * </table>
  *
+ * <p>Use loggers as usual:
+ * <ul>
+ *     <li>
+ *         Declare a logger<br/>
+ *         <code>private static final Logger logger = LoggerFactory.getLogger(MyClass.class);</code>
+ *     </li>
+ *     <li>
+ *         Invoke logging methods, e.g.,<br/>
+ *         <code>logger.debug("Some log message. Details: {}", someObject);</code><br/>
+ *         <code>logger.debug("Some log message with varargs. Details: {}, {}, {}", someObject1, someObject2, someObject3);</code>
+ *     </li>
+ * </ul>
+ * </p>
+ *
+ * <p>Logger instances created using the LoggerFactory are named either according to the name
+ * or the fully qualified class name of the class given as a parameter.
+ * Each logger name will be used as the log message tag on the Android platform.
+ * However, tag names cannot be longer than 23 characters so if logger name exceeds this limit then
+ * it will be truncated by the LoggerFactory. The following examples illustrate this.
+ * <table border="1">
+ * <tr><th><b>Original Name<b></th><th><b>Truncated Name</b></th></tr>
+ * <tr><td>org.example.myproject.mypackage.MyClass</td><td>o*.e*.m*.m*.MyClass</td></tr>
+ * <tr><td>o.e.myproject.mypackage.MyClass</td><td>o.e.m*.m*.MyClass</td></tr>
+ * <tr><td>org.example.ThisNameIsWayTooLongAndWillBeTruncated</td><td>*LongAndWillBeTruncated</td></tr>
+ * <tr><td>ThisNameIsWayTooLongAndWillBeTruncated</td><td>*LongAndWillBeTruncated</td></tr>
+ * </table>
+ * </p>
+ *
  * @author Andrey Korzhevskiy <a.korzhevskiy@gmail.com>
  */
 public class AndroidLoggerAdapter extends MarkerIgnoringBase {
diff --git a/slf4j-android/src/main/java/org/slf4j/impl/AndroidLoggerFactory.java b/slf4j-android/src/main/java/org/slf4j/impl/AndroidLoggerFactory.java
index 993380d0..46ee823a 100755
--- a/slf4j-android/src/main/java/org/slf4j/impl/AndroidLoggerFactory.java
+++ b/slf4j-android/src/main/java/org/slf4j/impl/AndroidLoggerFactory.java
@@ -39,19 +39,15 @@ import java.util.concurrent.ConcurrentMap;
 public class AndroidLoggerFactory implements ILoggerFactory {
     private final ConcurrentMap<String, Logger> loggerMap;
 
-    static final String ANONYMOUS_TAG = "null"; //taken from dalvik.system.DalvikLogging
-    static final int TAG_MAX_LENGTH = 23; // tag names cannot be longer on Android platform
-    // see also android/system/core/include/cutils/property.h
-    // and android/frameworks/base/core/jni/android_util_Log.cpp
+    static final String ANONYMOUS_TAG = "null";
+    static final int TAG_MAX_LENGTH = 23;
 
     public AndroidLoggerFactory() {
         loggerMap = new ConcurrentHashMap<String, Logger>();
     }
 
-    /*
-     * (non-Javadoc)
-     *
-     * @see org.slf4j.ILoggerFactory#getLogger(java.lang.String)
+    /**
+     * Return an appropriate {@link AndroidLoggerAdapter} instance by name.
      */
     public Logger getLogger(String name) {
         String tag = loggerNameToTag(name); // fix for bug #173
@@ -73,9 +69,17 @@ public class AndroidLoggerFactory implements ILoggerFactory {
     }
 
     /**
-     * Returns the short logger tag (up to {@value #TAG_MAX_LENGTH} chars) for the given logger name.
+     * Tag names cannot be longer than {@value #TAG_MAX_LENGTH} characters on Android platform.
+     *
+     * Returns the short logger tag (up to {@value #TAG_MAX_LENGTH} characters) for the given logger name.
      * Traditionally loggers are named by fully-qualified Java classes; this
      * method attempts to return a concise identifying part of such names.
+     *
+     * See also:
+     * android/system/core/include/cutils/property.h
+     * android/frameworks/base/core/jni/android_util_Log.cpp
+     * dalvik.system.DalvikLogging
+     *
      */
     static String loggerNameToTag(String loggerName) {
         // Anonymous logger