Added JavaDoc of ActivityInterface

Author: mfateev

src/main/java/com/uber/cadence/activity/ActivityInterface.java

@@ -17,19 +17,59 @@
 
 package com.uber.cadence.activity;
 
+import com.uber.cadence.workflow.Workflow;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
  * Indicates that the interface is an activity interface. Only interfaces annotated with this
- * annotation can be used as parameters to {@link
- * com.uber.cadence.workflow.Workflow#newActivityStub(Class)} methods.
+ * annotation can be used as parameters to {@link Workflow#newActivityStub(Class)} methods.
  *
  * <p>Each method of the interface annotated with <code>ActivityInterface</code> including inherited
  * from interfaces is a separate activity. By default the name of an activity type is "short
  * interface name"_"method name".
+ *
+ * <p>Example:
+ *
+ * <pre><code>
+ *  public interface A {
+ *      a();
+ *  }
+ *
+ * {@literal @}ActivityInterface
+ *  public interface B extends A {
+ *     b();
+ *  }
+ *
+ * {@literal @}ActivityInterface
+ *  public interface C extends B {
+ *     c();
+ *  }
+ *
+ *  public class CImpl implements C {
+ *      public void a() {}
+ *      public void b() {}
+ *      public void c() {}
+ *  }
+ * </code></pre>
+ *
+ * When <code>CImpl</code> instance is registered with the {@link com.uber.cadence.worker.Worker} the
+ * following activities are registered:
+ *
+ * <p>
+ *
+ * <ul>
+ *   <li>B_a
+ *   <li>B_b
+ *   <li>C_c
+ * </ul>
+ *
+ * Note that method <code>a()</code> is registered as "B_a" because interface <code>A</code> lacks
+ * ActivityInterface annotation. The workflow code can call activities through stubs to <code>B
+ * </code> and <code>C</code> interfaces. A call to crate stub to <code>A</code> interface will fail
+ * as <code>A</code> is not annotated with ActivityInterface.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)