From b4db3856bdd53ec76c10a48b94262164a1bbc645 Mon Sep 17 00:00:00 2001
From: Maxim Fateev <mfateev@gmail.com>
Date: Thu, 2 Apr 2020 16:20:59 -0700
Subject: [PATCH] Added JavaDoc of ActivityInterface

---
 .../cadence/activity/ActivityInterface.java   | 44 ++++++++++++++++++-
 1 file changed, 42 insertions(+), 2 deletions(-)

diff --git a/src/main/java/com/uber/cadence/activity/ActivityInterface.java b/src/main/java/com/uber/cadence/activity/ActivityInterface.java
index f29f28c93..9a0dd45c5 100644
--- a/src/main/java/com/uber/cadence/activity/ActivityInterface.java
+++ b/src/main/java/com/uber/cadence/activity/ActivityInterface.java
@@ -17,6 +17,7 @@
 
 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;
@@ -24,12 +25,51 @@
 
 /**
  * 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)