docs: Clarify the relationship between Status*Exception

ejona86 · ejona86 · commit 7c44a4e11197 · 2016-08-04T15:33:31.000-07:00
diff --git a/core/src/main/java/io/grpc/StatusException.java b/core/src/main/java/io/grpc/StatusException.java
@@ -34,9 +34,9 @@
 import javax.annotation.Nullable;
 
 /**
- * {@link Status} in Exception form, for propagating Status information via exceptions.
- *
- * @see StatusRuntimeException
+ * {@link Status} in Exception form, for propagating Status information via exceptions. This is
+ * semantically equivalent to {@link StatusRuntimeException}, except for usage in APIs that promote
+ * checked exceptions. gRPC's stubs favor {@code StatusRuntimeException}.
  */
 public class StatusException extends Exception {
   private static final long serialVersionUID = -660954903976144640L;
