Add comments about component, abstractSpan

apm-network/src/main/java/org/skywalking/apm/network/trace/component/Component.java

@@ -1,6 +1,11 @@
 package org.skywalking.apm.network.trace.component;
 
 /**
+ * The <code>Component</code> represents component library,
+ * which has been supported by skywalking sniffer.
+ *
+ * The supported list is in {@link ComponentsDefine}.
+ *
  * @author wusheng
  */
 public interface Component {

apm-network/src/main/java/org/skywalking/apm/network/trace/component/ComponentsDefine.java

@@ -1,6 +1,8 @@
 package org.skywalking.apm.network.trace.component;
 
 /**
+ * The supported list of skywalking java sniffer.
+ *
  * @author wusheng
  */
 public class ComponentsDefine {

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

@@ -11,10 +11,19 @@ import org.skywalking.apm.network.trace.component.Component;
 public interface AbstractSpan {
     /**
      * Set the component id, which defines in {@link org.skywalking.apm.network.trace.component.ComponentsDefine}
+     *
      * @param component
+     * @return the span for chaining.
      */
     AbstractSpan setComponent(Component component);
 
+    /**
+     * Only use this method in explicit instrumentation, like opentracing-skywalking-bridge.
+     * It it higher recommend don't use this for performance consideration.
+     *
+     * @param componentName
+     * @return the span for chaining.
+     */
     AbstractSpan setComponent(String componentName);
 
     AbstractSpan setLayer(SpanLayer layer);

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

@@ -129,16 +129,35 @@ public abstract class AbstractTracingSpan implements AbstractSpan {
         return this;
     }
 
+    /**
+     * In the scope of this span tracing context, error occurred,
+     * in auto-instrumentation mechanism, almost means throw an exception.
+     *
+     * @return span instance, for chaining.
+     */
     public AbstractSpan errorOccurred() {
         this.errorOccurred = true;
         return this;
     }
 
+    /**
+     * Set the operation name, just because these is not compress dictionary value for this name.
+     * Use the entire string temporarily, the agent will compress this name in async mode.
+     *
+     * @param operationName
+     * @return span instance, for chaining.
+     */
     public AbstractTracingSpan setOperationName(String operationName) {
         this.operationName = operationName;
         return this;
     }
 
+    /**
+     * Set the operation id, which compress by the name.
+     *
+     * @param operationId
+     * @return span instance, for chaining.
+     */
     public AbstractTracingSpan setOperationId(int operationId) {
         this.operationId = operationId;
         return this;
@@ -162,12 +181,26 @@ public abstract class AbstractTracingSpan implements AbstractSpan {
         return this;
     }
 
+    /**
+     * Set the component of this span, with internal supported.
+     * Highly recommend to use this way.
+     *
+     * @param component
+     * @return span instance, for chaining.
+     */
     @Override
     public AbstractSpan setComponent(Component component) {
         this.componentId = component.getId();
         return this;
     }
 
+    /**
+     * Set the component name.
+     * By using this, cost more memory and network.
+     *
+     * @param componentName
+     * @return span instance, for chaining.
+     */
     @Override
     public AbstractSpan setComponent(String componentName) {
         this.componentName = componentName;