Add comments for major class in agent-core.

apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/ContextManager.java

@@ -119,7 +119,9 @@ public class ContextManager implements TracingContextListener, BootService, Igno
         if (carrier == null) {
             throw new IllegalArgumentException("ContextCarrier can't be null.");
         }
-        get().extract(carrier);
+        if (carrier.isValid()) {
+            get().extract(carrier);
+        }
     }
 
     public ContextSnapshot capture() {
@@ -130,7 +132,9 @@ public class ContextManager implements TracingContextListener, BootService, Igno
         if (snapshot == null) {
             throw new IllegalArgumentException("ContextSnapshot can't be null.");
         }
-        get().continued(snapshot);
+        if (snapshot.isValid()) {
+            get().continued(snapshot);
+        }
     }
 
     public static AbstractSpan activeSpan() {

apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/ContextSnapshot.java

@@ -4,13 +4,20 @@ import java.util.List;
 import org.skywalking.apm.agent.core.context.ids.DistributedTraceId;
 
 /**
- * The <code>ContextSnapshot</code> is a snapshot for current context.
+ * The <code>ContextSnapshot</code> is a snapshot for current context. The snapshot carries the info for building
+ * reference between two segments in two thread, but have a causal relationship.
  *
  * @author wusheng
  */
 public class ContextSnapshot {
+    /**
+     * trace segment id of the parent trace segment.
+     */
     private String traceSegmentId;
 
+    /**
+     * span id of the parent span, in parent trace segment.
+     */
     private int spanId = -1;
 
     /**
@@ -36,4 +43,11 @@ public class ContextSnapshot {
     public int getSpanId() {
         return spanId;
     }
+
+    public boolean isValid() {
+        return traceSegmentId != null
+            && spanId > -1
+            && distributedTraceIds != null
+            && distributedTraceIds.size() > 0;
+    }
 }

apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/IgnoredTracerContext.java

@@ -7,8 +7,9 @@ import org.skywalking.apm.agent.core.context.trace.NoopSpan;
 
 /**
  * The <code>IgnoredTracerContext</code> represent a context should be ignored.
- * So it just maintains the stack with integer depth.
- * All operations through this <code>IgnoredTracerContext</code> will be ignored, with low gc cost.
+ * So it just maintains the stack with an integer depth field.
+ *
+ * All operations through this will be ignored, and keep the memory and gc cost as low as possible.
  *
  * @author wusheng
  */

apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/TracingContext.java

@@ -112,12 +112,24 @@ public class TracingContext implements AbstractTracerContext {
         carrier.setDistributedTraceIds(this.segment.getRelatedGlobalTraces());
     }
 
+    /**
+     * Extract the carrier to build the reference for the pre segment.
+     *
+     * @param carrier carried the context from a cross-process segment.
+     * @see {@link AbstractTracerContext#extract(ContextCarrier)}
+     */
     @Override
     public void extract(ContextCarrier carrier) {
         this.segment.ref(new TraceSegmentRef(carrier));
         this.segment.relatedGlobalTraces(carrier.getDistributedTraceIds());
     }
 
+    /**
+     * Capture the snapshot of current context.
+     *
+     * @return the snapshot of context for cross-thread propagation
+     * @see {@link AbstractTracerContext#capture()}
+     */
     @Override
     public ContextSnapshot capture() {
         return new ContextSnapshot(segment.getTraceSegmentId(),
@@ -126,17 +138,33 @@ public class TracingContext implements AbstractTracerContext {
         );
     }
 
+    /**
+     * Continue the context from the given snapshot of parent thread.
+     *
+     * @param snapshot from {@link #capture()} in the parent thread.
+     * @see {@link AbstractTracerContext#continued(ContextSnapshot)}
+     */
     @Override
     public void continued(ContextSnapshot snapshot) {
         this.segment.ref(new TraceSegmentRef(snapshot));
         this.segment.relatedGlobalTraces(snapshot.getDistributedTraceIds());
     }
 
+    /**
+     * @return the first global trace id.
+     */
     @Override
     public String getGlobalTraceId() {
         return segment.getRelatedGlobalTraces().get(0).get();
     }
 
+    /**
+     * Create an entry span
+     *
+     * @param operationName most likely a service name
+     * @return span instance.
+     * @see {@link EntrySpan}
+     */
     @Override
     public AbstractSpan createEntrySpan(final String operationName) {
         AbstractTracingSpan entrySpan;
@@ -174,6 +202,13 @@ public class TracingContext implements AbstractTracerContext {
         }
     }
 
+    /**
+     * Create a local span
+     *
+     * @param operationName most likely a local method signature, or business name.
+     * @return the span represents a local logic block.
+     * @see {@link LocalSpan}
+     */
     @Override
     public AbstractSpan createLocalSpan(final String operationName) {
         AbstractTracingSpan parentSpan = peek();
@@ -195,6 +230,14 @@ public class TracingContext implements AbstractTracerContext {
         return push(span);
     }
 
+    /**
+     * Create an exit span
+     *
+     * @param operationName most likely a service name of remote
+     * @param remotePeer the network id(ip:port, hostname:port or ip1:port1,ip2,port, etc.)
+     * @return the span represent an exit point of this segment.
+     * @see {@link ExitSpan}
+     */
     @Override
     public AbstractSpan createExitSpan(final String operationName, final String remotePeer) {
         AbstractTracingSpan exitSpan;
@@ -236,6 +279,9 @@ public class TracingContext implements AbstractTracerContext {
         return exitSpan;
     }
 
+    /**
+     * @return the active span of current context, the top element of {@link #activeSpanStack}
+     */
     @Override
     public AbstractTracingSpan activeSpan() {
         AbstractTracingSpan span = peek();
@@ -245,6 +291,12 @@ public class TracingContext implements AbstractTracerContext {
         return span;
     }
 
+    /**
+     * Stop the given span, if and only if this one is the top element of {@link #activeSpanStack}.
+     * Because the tracing core must make sure the span must match in a stack module, like any program did.
+     *
+     * @param span to finish
+     */
     @Override
     public void stopSpan(AbstractSpan span) {
         AbstractTracingSpan lastSpan = peek();
@@ -281,6 +333,10 @@ public class TracingContext implements AbstractTracerContext {
         TracingContext.ListenerManager.notifyFinish(finishedSegment);
     }
 
+    /**
+     * The <code>ListenerManager</code> represents an event notify for every registered listener, which are notified
+     * when the <cdoe>TracingContext</cdoe> finished, and {@link #segment} is ready for further process.
+     */
     public static class ListenerManager {
         private static List<TracingContextListener> LISTENERS = new LinkedList<TracingContextListener>();
 

apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/trace/EntrySpan.java

@@ -6,11 +6,14 @@ import org.skywalking.apm.network.trace.component.Component;
 /**
  * The <code>EntrySpan</code> represents a service provider point, such as Tomcat server entrance.
  *
- * It is a start point of {@link TraceSegment}, even in a complex application, there maybe have multi entry point,
+ * It is a start point of {@link TraceSegment}, even in a complex application, there maybe have multi-layer entry point,
  * the <code>EntrySpan</code> only represents the first one.
  *
  * But with the last <code>EntrySpan</code>'s tags and logs, which have more details about a service provider.
  *
+ * Such as: Tomcat Embed -> Dubbox
+ * The <code>EntrySpan</code> represents the Dubbox span.
+ *
  * @author wusheng
  */
 public class EntrySpan extends AbstractTracingSpan {

apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/trace/ExitSpan.java

@@ -5,13 +5,16 @@ import org.skywalking.apm.network.proto.SpanObject;
 import org.skywalking.apm.network.trace.component.Component;
 
 /**
- * The <code>ExitSpan</code> represents a service consumer point, such as Feign, Okhttp discovery for a Http service.
+ * The <code>ExitSpan</code> represents a service consumer point, such as Feign, Okhttp client for a Http service.
  *
  * It is an exit point or a leaf span(our old name) of trace tree.
- * In a single rpc call, because of a combination of discovery libs, there maybe contain multi exit point.
+ * In a single rpc call, because of a combination of discovery libs, there maybe contain multi-layer exit point:
  *
  * The <code>ExitSpan</code> only presents the first one.
  *
+ * Such as: Dubbox -> Apache Httpcomponent -> ....(Remote)
+ * The <code>ExitSpan</code> represents the Dubbox span, and ignore the httpcomponent span's info.
+ *
  * @author wusheng
  */
 public class ExitSpan extends AbstractTracingSpan {

apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/trace/NoopSpan.java

@@ -5,7 +5,8 @@ import org.skywalking.apm.network.trace.component.Component;
 
 /**
  * The <code>NoopSpan</code> represents a span implementation without any actual operation.
- * This span implementation is for {@link IgnoredTracerContext}.
+ * This span implementation is for {@link IgnoredTracerContext},
+ * for keeping the memory and gc cost as low as possible.
  *
  * @author wusheng
  */
@@ -13,7 +14,6 @@ public class NoopSpan implements AbstractSpan {
     public NoopSpan() {
     }
 
-
     @Override
     public AbstractSpan log(Throwable t) {
         return this;
@@ -23,7 +23,7 @@ public class NoopSpan implements AbstractSpan {
         return null;
     }
 
-    public void finish(){
+    public void finish() {
 
     }