Optimize codes and add more comments.

apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/conf/RemoteDownstreamConfig.java

@@ -5,6 +5,9 @@ import java.util.List;
 import org.skywalking.apm.agent.core.dictionary.DictionaryUtil;
 
 /**
+ * The <code>RemoteDownstreamConfig</code> includes configurations from collector side.
+ * All of them initialized null, Null-Value or empty collection.
+ *
  * @author wusheng
  */
 public class RemoteDownstreamConfig {

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

 package org.skywalking.apm.agent.core.context;
 
 import org.skywalking.apm.agent.core.context.trace.AbstractSpan;
+import org.skywalking.apm.agent.core.context.trace.EntrySpan;
+import org.skywalking.apm.agent.core.context.trace.ExitSpan;
+import org.skywalking.apm.agent.core.context.trace.LocalSpan;
 
 /**
  * The <code>AbstractTracerContext</code> represents the tracer context manager.
@@ -8,23 +11,89 @@ import org.skywalking.apm.agent.core.context.trace.AbstractSpan;
  * @author wusheng
  */
 public interface AbstractTracerContext {
+    /**
+     * Prepare for the cross-process propagation.
+     * How to initialize the carrier, depends on the implementation.
+     *
+     * @param carrier to carry the context for crossing process.
+     * @see {@link TracingContext} and {@link IgnoredTracerContext}
+     */
     void inject(ContextCarrier carrier);
 
+    /**
+     * Build the reference between this segment and a cross-process segment.
+     * How to build, depends on the implementation.
+     *
+     * @param carrier carried the context from a cross-process segment.
+     * @see {@link TracingContext} and {@link IgnoredTracerContext}
+     */
     void extract(ContextCarrier carrier);
 
+    /**
+     * Capture a snapshot for cross-thread propagation.
+     * It's a similar concept with ActiveSpan.Continuation in OpenTracing-java
+     * How to build, depends on the implementation.
+     *
+     * @return the {@link ContextSnapshot} , which includes the reference context.
+     * @see {@link TracingContext} and {@link IgnoredTracerContext}
+     */
     ContextSnapshot capture();
 
+    /**
+     * Build the reference between this segment and a cross-thread segment.
+     * How to build, depends on the implementation.
+     *
+     * @param snapshot from {@link #capture()} in the parent thread.
+     * @see {@link TracingContext} and {@link IgnoredTracerContext}
+     */
     void continued(ContextSnapshot snapshot);
 
+    /**
+     * Get the global trace id, if exist.
+     * How to build, depends on the implementation.
+     *
+     * @return the string represents the id.
+     * @see {@link TracingContext} and {@link IgnoredTracerContext}
+     */
     String getGlobalTraceId();
 
+    /**
+     * Create an entry span
+     *
+     * @param operationName most likely a service name
+     * @return the span represents an entry point of this segment.
+     * @see {@link EntrySpan} if the implementation is {@link TracingContext}
+     */
     AbstractSpan createEntrySpan(String operationName);
 
+    /**
+     * 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} if the implementation is {@link TracingContext}
+     */
     AbstractSpan createLocalSpan(String operationName);
 
+    /**
+     * 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} if the implementation is {@link TracingContext}
+     */
     AbstractSpan createExitSpan(String operationName, String remotePeer);
 
+    /**
+     * @return the active span of current tracing context(stack)
+     */
     AbstractSpan activeSpan();
 
+    /**
+     * Finish the given span, and the given span should be the active span of current tracing context(stack)
+     *
+     * @param span to finish
+     */
     void stopSpan(AbstractSpan span);
 }

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

@@ -108,25 +108,11 @@ public class ContextManager implements TracingContextListener, BootService, Igno
     }
 
     public static void inject(ContextCarrier contextCarrier) {
-        AbstractSpan span = activeSpan();
-        if (span instanceof AbstractTracingSpan) {
-            if (span.isExit()) {
-                get().inject(contextCarrier);
-            } else {
-                throw new IllegalStateException("Can't do inject when the active span isn't an exit span");
-            }
-        }
+        get().inject(contextCarrier);
     }
 
     public static void extract(ContextCarrier contextCarrier) {
-        AbstractSpan span = activeSpan();
-        if (span instanceof AbstractTracingSpan) {
-            if (span.isEntry()) {
-                get().extract(contextCarrier);
-            } else {
-                throw new IllegalStateException("Can't do extract when the active span isn't an entry span");
-            }
-        }
+        get().extract(contextCarrier);
     }
 
     public ContextSnapshot capture() {

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

@@ -16,11 +16,29 @@ import org.skywalking.apm.agent.core.dictionary.PossibleFound;
 import org.skywalking.apm.agent.core.sampling.SamplingService;
 
 /**
+ * The <code>TracingContext</code> represents a core tracing logic controller.
+ * It build the final {@link TracingContext}, by the stack mechanism,
+ * which is similar with the codes work.
+ *
+ * In opentracing concept, it means, all spans in a segment tracing context(thread)
+ * are CHILD_OF relationship, but no FOLLOW_OF.
+ *
+ * In skywalking core concept, FOLLOW_OF is an abstract concept
+ * when cross-process MQ or cross-thread async/batch tasks happen,
+ * we used {@link TraceSegmentRef} for these scenarios.
+ * Check {@link TraceSegmentRef} which is from {@link ContextCarrier} or {@link ContextSnapshot}.
+ *
  * @author wusheng
  */
 public class TracingContext implements AbstractTracerContext {
+    /**
+     * @see {@link SamplingService}
+     */
     private SamplingService samplingService;
 
+    /**
+     * The final {@link TraceSegment}, which includes all finished spans.
+     */
     private TraceSegment segment;
 
     /**
@@ -32,8 +50,14 @@ public class TracingContext implements AbstractTracerContext {
      */
     private LinkedList<AbstractTracingSpan> activeSpanStack = new LinkedList<AbstractTracingSpan>();
 
+    /**
+     * A counter for the next span.
+     */
     private int spanIdGenerator;
 
+    /**
+     * Initialize all fields with default value.
+     */
     TracingContext() {
         this.segment = new TraceSegment();
         this.spanIdGenerator = 0;
@@ -42,6 +66,13 @@ public class TracingContext implements AbstractTracerContext {
         }
     }
 
+    /**
+     * Inject the context into the given carrier, only when the active span is an exit one.
+     *
+     * @param carrier to carry the context for crossing process.
+     * @see {@link AbstractTracerContext#inject(ContextCarrier)}
+     * @throws IllegalStateException, if the active span isn't an exit one.
+     */
     @Override
     public void inject(ContextCarrier carrier) {
         AbstractTracingSpan span = this.activeSpan();