From f5de30b1013b49358acec4e52a41b45ced2f7802 Mon Sep 17 00:00:00 2001
From: wusheng <wu.sheng@foxmail.com>
Date: Mon, 9 Jan 2017 09:59:04 +0800
Subject: [PATCH] =?UTF-8?q?Add=20comments=20in=20=E2=80=9Clogging-api?=
 =?UTF-8?q?=E2=80=9D=20module=20.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../main/java/com/a/eye/skywalking/logging/api/ILog.java  | 4 ++++
 .../java/com/a/eye/skywalking/logging/api/LogManager.java | 8 ++++++++
 .../com/a/eye/skywalking/logging/api/LogResolver.java     | 6 ++++++
 .../java/com/a/eye/skywalking/logging/api/NoopLogger.java | 5 ++++-
 4 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/ILog.java b/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/ILog.java
index 8a3a52a85..dfe6a4067 100644
--- a/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/ILog.java
+++ b/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/ILog.java
@@ -1,6 +1,10 @@
 package com.a.eye.skywalking.logging.api;
 
 /**
+ * The Log interface.
+ * It's very easy to understand, like any other log-component.
+ * Do just like log4j or log4j2 does.
+ * <p>
  * Created by xin on 2016/11/10.
  */
 public interface ILog {
diff --git a/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/LogManager.java b/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/LogManager.java
index 6683ef226..19497e286 100644
--- a/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/LogManager.java
+++ b/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/LogManager.java
@@ -1,6 +1,14 @@
 package com.a.eye.skywalking.logging.api;
 
 /**
+ * LogManager is the {@link LogResolver} implementation manager.
+ * By using {@link LogResolver}, {@link LogManager#getLogger(Class)} returns a {@link ILog} implementation.
+ * This module use this class as the main entrance, and block the implementation detail about log-component.
+ * In different modules, like server or sniffer, it will use different implementations.
+ * <p>
+ * If no {@link LogResolver} is registered, return {@link NoopLogger#INSTANCE} to avoid {@link NullPointerException}.
+ * If {@link LogManager#setLogResolver(LogResolver)} is called twice, the second will override the first without any warning or exception.
+ * <p>
  * Created by xin on 2016/11/10.
  */
 public class LogManager {
diff --git a/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/LogResolver.java b/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/LogResolver.java
index 627792ea3..0a50cef91 100644
--- a/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/LogResolver.java
+++ b/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/LogResolver.java
@@ -1,8 +1,14 @@
 package com.a.eye.skywalking.logging.api;
 
 /**
+ * {@link LogResolver} just do only one thing: return the {@link ILog} implementation.
+ * <p>
  * Created by xin on 2016/11/10.
  */
 public interface LogResolver {
+    /**
+     * @param clazz, the class is showed in log message.
+     * @return {@link ILog} implementation.
+     */
     ILog getLogger(Class<?> clazz);
 }
diff --git a/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/NoopLogger.java b/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/NoopLogger.java
index 684f98eeb..936c13bb5 100644
--- a/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/NoopLogger.java
+++ b/skywalking-commons/skywalking-logging/skywalking-logging-api/src/main/java/com/a/eye/skywalking/logging/api/NoopLogger.java
@@ -2,9 +2,12 @@ package com.a.eye.skywalking.logging.api;
 
 
 /**
+ * No operation logger implementation.
+ * Just implement {@link ILog} interface, but do nothing.
+ * <p>
  * Created by xin on 2016/11/10.
  */
-public class NoopLogger implements ILog{
+public class NoopLogger implements ILog {
     public static final ILog INSTANCE = new NoopLogger();
 
     @Override