Docs: update javadoc for @CalledByNative/Unchecked

No change to logic, only docs. This updates the Javadoc for
@CalledByNative and @CalledByNativeUnchecked to clarify the difference
and how each of them behave with respect to Java exceptions. This info
is based on an offline conversation with torne@.

Test: N/A
Change-Id: I4fe7d14d10d5f35abb8db6d6fffe9b680613a2b8
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2504406Reviewed-by: Richard Coles <torne@chromium.org>
Commit-Queue: Nate Fischer <ntfschr@chromium.org>
Cr-Commit-Position: refs/heads/master@{#821737}

base/android/java/src/org/chromium/base/annotations/CalledByNative.java

@@ -10,8 +10,13 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * @CalledByNative is used by the JNI generator to create the necessary JNI
- * bindings and expose this method to native code.
+ * Used by the JNI generator to create the necessary JNI bindings and expose this method to native
+ * code.
+ *
+ * <p>Any uncaught Java exceptions will crash the current process. This is generally the desired
+ * behavior, since most exceptions indicate an unexpected error. If your java method expects an
+ * exception, we recommend refactoring to catch exceptions and indicate errors with special return
+ * values instead. If this is not possible, see {@link CalledByNativeUnchecked} instead.
  */
 @Target({ElementType.CONSTRUCTOR, ElementType.METHOD})
 @Retention(RetentionPolicy.CLASS)

base/android/java/src/org/chromium/base/annotations/CalledByNativeUnchecked.java

@@ -10,12 +10,14 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- *  @CalledByNativeUnchecked is used to generate JNI bindings that do not check for exceptions.
- *  It only makes sense to use this annotation on methods that declare a throws... spec.
- *  However, note that the exception received native side maybe an 'unchecked' (RuntimeExpception)
- *  such as NullPointerException, so the native code should differentiate these cases.
- *  Usage of this should be very rare; where possible handle exceptions in the Java side and use a
- *  return value to indicate success / failure.
+ * Similar to {@link CalledByNative}, this also exposes JNI bindings to native code. The main
+ * difference is this <b>will not</b> crash the browser process if the Java method throws an
+ * exception. However, the C++ caller <b>must</b> handle and clear the exception before calling into
+ * any other Java code, otherwise the next Java method call will crash (with the previous call's
+ * exception, which leads to a very confusing debugging experience).
+ *
+ * <p>Usage of this annotation should be very rare; due to the complexity of correctly handling
+ * exceptions in C++, prefer using {@link CalledByNative}.
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.CLASS)