Docs: explain how to out-of-line return values

This adds a section to explain how to out-of-line methods which return
or accept new types. This isn't generally necessary for implementation
code, but this is important for external-facing classes (such as
WebView's glue layer).

Fixed: 1112420
Test: Upload to gerrit > open file > click "gitiles"
Change-Id: Ia5f835663780c50e1d1601e969a5a6d550e9fbf5
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2493430
Commit-Queue: Nate Fischer <ntfschr@chromium.org>
Reviewed-by: Mohamed Heikal <mheikal@chromium.org>
Cr-Commit-Position: refs/heads/master@{#820381}

build/android/docs/class_verification_failures.md

@@ -146,6 +146,46 @@ public class ApiHelperForOMR1 {
 * Don't put any `SDK_INT` checks inside this class, because it must only be
   called on >= OMR1.
 
+### Out-of-lining if your method has a new type in its signature
+
+Sometimes you'll run into a situation where a class **needs** to have a method
+which either accepts a parameter which is a new type or returns a new type
+(e.g., externally-facing code, such as WebView's glue layer). Even though it's
+impossible to write such a class without referring to the new type, it's still
+possible to avoid failing class verification. ART has a useful optimization: if
+your class only moves a value between registers (i.e., it doesn't call any
+methods or fields on the value), then ART will not check for the existence of
+that value's type. This means you can write your class like so:
+
+```java
+public class FooBar {
+    // FooBar needs to have the getNewTypeInAndroidP method, but it would be
+    // expensive to fail verification. This method will only be called on >= P
+    // but other methods on the class will be used on lower OS versions (and
+    // also can't be factored into another class).
+    public NewTypeInAndroidP getNewTypeInAndroidP() {
+        assert Build.VERSION.SDK_INT >= Build.VERSION_CODES.P;
+        // Stores a NewTypeInAndroidP in the return register, but doesn't do
+        // anything else with it
+        return ApiHelperForP.getNewTypeInAndroidP();
+    }
+
+    // ...
+}
+
+@VerifiesOnP
+@TargetApi(Build.VERSION_CODES.P)
+public class ApiHelperForP {
+    public static NewTypeInAndroidP getNewTypeInAndroidP() {
+        return new NewTypeInAndroidP();
+    }
+
+    // ...
+}
+```
+
+**Note:** this only works in ART (L+), not Dalvik (KitKat and earlier).
+
 ## Investigating class verification failures
 
 Class verification is generally surprising and nonintuitive. Fortunately, the