Update Typeface callback docs about error codes

As requested by API council, mention that the provider may
return its own error codes within the positive int range.

Bug: 37084803
Test: none
Change-Id: Ia8ee99432cc5025a12d43049e327605095dd2b57

diff --git a/core/java/android/provider/FontsContract.java b/core/java/android/provider/FontsContract.java
index e9ef770..fe48f55 100644 (file)
--- a/core/java/android/provider/FontsContract.java
+++ b/core/java/android/provider/FontsContract.java
@@ -124,8 +124,9 @@ public class FontsContract {
          * should have this column populated to indicate the result status of the
          * query. This will be checked before any other data in the cursor. Possible values are
          * {@link #RESULT_CODE_OK}, {@link #RESULT_CODE_FONT_NOT_FOUND},
-         * {@link #RESULT_CODE_MALFORMED_QUERY} and {@link #RESULT_CODE_FONT_UNAVAILABLE}. If not
-         * present, {@link #RESULT_CODE_OK} will be assumed.
+         * {@link #RESULT_CODE_MALFORMED_QUERY} and {@link #RESULT_CODE_FONT_UNAVAILABLE} for system
+         * defined values. You may also define your own values in the 0x000010000..0xFFFF0000 range.
+         * If not present, {@link #RESULT_CODE_OK} will be assumed.
          */
         public static final String RESULT_CODE = "result_code";
 
@@ -452,7 +453,10 @@ public class FontsContract {
          *               {@link #FAIL_REASON_FONT_NOT_FOUND},
          *               {@link #FAIL_REASON_FONT_LOAD_ERROR},
          *               {@link #FAIL_REASON_FONT_UNAVAILABLE} or
-         *               {@link #FAIL_REASON_MALFORMED_QUERY}.
+         *               {@link #FAIL_REASON_MALFORMED_QUERY} if returned by the system. May also be
+         *               a positive value greater than 0 defined by the font provider as an
+         *               additional error code. Refer to the provider's documentation for more
+         *               information on possible returned error codes.
          */
         public void onTypefaceRequestFailed(@FontRequestFailReason int reason) {}
     }

diff --git a/graphics/java/android/graphics/Typeface.java b/graphics/java/android/graphics/Typeface.java
index 97d3e5e..b17dc5b 100644 (file)
--- a/graphics/java/android/graphics/Typeface.java
+++ b/graphics/java/android/graphics/Typeface.java
@@ -475,11 +475,14 @@ public class Typeface {
         /**
          * Called when a Typeface request done via {@link Typeface#create(FontRequest,
          * FontRequestCallback)} fails.
-         * @param reason One of {@link #FAIL_REASON_PROVIDER_NOT_FOUND},
+         * @param reason May be one of {@link #FAIL_REASON_PROVIDER_NOT_FOUND},
          *               {@link #FAIL_REASON_FONT_NOT_FOUND},
          *               {@link #FAIL_REASON_FONT_LOAD_ERROR},
          *               {@link #FAIL_REASON_FONT_UNAVAILABLE} or
-         *               {@link #FAIL_REASON_MALFORMED_QUERY}.
+         *               {@link #FAIL_REASON_MALFORMED_QUERY} if returned by the system. May also be
+         *               a positive value greater than 0 defined by the font provider as an
+         *               additional error code. Refer to the provider's documentation for more
+         *               information on possible returned error codes.
          */
         void onTypefaceRequestFailed(@FontRequestFailReason int reason);
     }