Improved documentation of AutofillFieldClassificationService.onGetScores()
Test: echo 'In TH we trust!'
Fixes: 74830976
Change-Id: Ia1c002fa3b340810789b9cca9d7c4b71ea083230
diff --git a/core/java/android/service/autofill/AutofillFieldClassificationService.java b/core/java/android/service/autofill/AutofillFieldClassificationService.java
index cf16749..99d45f4 100644
--- a/core/java/android/service/autofill/AutofillFieldClassificationService.java
+++ b/core/java/android/service/autofill/AutofillFieldClassificationService.java
@@ -113,23 +113,67 @@
/**
* Calculates field classification scores in a batch.
*
- * <p>See {@link AutofillFieldClassificationService} for more info about field classification
- * scores.
+ * <p>A field classification score is a {@code float} representing how well an
+ * {@link AutofillValue} filled matches a expected value predicted by an autofill service
+ * —a full-match is {@code 1.0} (representing 100%), while a full mismatch is {@code 0.0}.
*
- * @param algorithm name of the algorithm to be used to calculate the scores. If invalid, the
- * default algorithm will be used instead.
- * @param args optional arguments to be passed to the algorithm.
+ * <p>The exact score depends on the algorithm used to calculate it— the service must
+ * provide at least one default algorithm (which is used when the algorithm is not specified
+ * or is invalid), but it could provide more (in which case the algorithm name should be
+ * specifiied by the caller when calculating the scores).
+ *
+ * <p>For example, if the service provides an algorithm named {@code EXACT_MATCH} that
+ * returns {@code 1.0} if all characters in match or {@code 0.0} otherwise, a call to:
+ *
+ * <pre>
+ * service.onGetScores("EXACT_MATCH", null,
+ * Arrays.asList(AutofillValue.forText("email1"), AutofillValue.forText("PHONE1")),
+ * Arrays.asList("email1", "phone1"));
+ * </pre>
+ *
+ * <p>Returns:
+ *
+ * <pre>
+ * [
+ * [1.0, 0.0], // "email1" compared against ["email1", "phone1"]
+ * [0.0, 0.0] // "PHONE1" compared against ["email1", "phone1"]
+ * ];
+ * </pre>
+ *
+ * <p>If the same algorithm allows the caller to specify whether the comparisons should be
+ * case sensitive by passing a boolean option named {@code "case_sensitive"}, then a call to:
+ *
+ * <pre>
+ * Bundle algorithmOptions = new Bundle();
+ * algorithmOptions.putBoolean("case_sensitive", false);
+ *
+ * service.onGetScores("EXACT_MATCH", algorithmOptions,
+ * Arrays.asList(AutofillValue.forText("email1"), AutofillValue.forText("PHONE1")),
+ * Arrays.asList("email1", "phone1"));
+ * </pre>
+ *
+ * <p>Returns:
+ *
+ * <pre>
+ * [
+ * [1.0, 0.0], // "email1" compared against ["email1", "phone1"]
+ * [0.0, 1.0] // "PHONE1" compared against ["email1", "phone1"]
+ * ];
+ * </pre>
+ *
+ * @param algorithm name of the algorithm to be used to calculate the scores. If invalid or
+ * {@code null}, the default algorithm is used instead.
+ * @param algorithmOptions optional arguments to be passed to the algorithm.
* @param actualValues values entered by the user.
* @param userDataValues values predicted from the user data.
- * @return the calculated scores, with the first dimension representing actual values and the
- * second dimension values from {@link UserData}.
+ * @return the calculated scores of {@code actualValues} x {@code userDataValues}.
*
* {@hide}
*/
@Nullable
@SystemApi
public float[][] onGetScores(@Nullable String algorithm,
- @Nullable Bundle args, @NonNull List<AutofillValue> actualValues,
+ @Nullable Bundle algorithmOptions, @NonNull List<AutofillValue> actualValues,
@NonNull List<String> userDataValues) {
Log.e(TAG, "service implementation (" + getClass() + " does not implement onGetScore()");
return null;