Merge "Fill in javadocs for translation feature." into sc-dev am: 1553fc7fad am: 44ef83555f am: c6caf136f5

Original change: https://googleplex-android-review.googlesource.com/c/platform/frameworks/base/+/15597859

Change-Id: If47d2f678466ccf67feed85d21f15090d5608d56

5 files changed, 52 insertions, 35 deletions

diff --git a/core/java/android/service/translation/ITranslationService.aidl b/core/java/android/service/translation/ITranslationService.aidl
index e9dd2c3bd70b..4cc732ab5a30 100644
--- a/core/java/android/service/translation/ITranslationService.aidl
+++ b/core/java/android/service/translation/ITranslationService.aidl
@@ -24,7 +24,7 @@ import com.android.internal.os.IResultReceiver;
 /**
  * System-wide on-device translation service.
  *
- * <p>Services requests to translate text between different languages. The primary use case for this
+ * <p>Services requests to translate data between different languages. The primary use case for this
  * service is automatic translation of text and web views, when the auto Translate feature is
  * enabled.
  *
diff --git a/core/java/android/service/translation/TranslationService.java b/core/java/android/service/translation/TranslationService.java
index 93c006aff435..d454c393a7ce 100644
--- a/core/java/android/service/translation/TranslationService.java
+++ b/core/java/android/service/translation/TranslationService.java
@@ -48,6 +48,7 @@ import android.view.translation.TranslationManager;
 import android.view.translation.TranslationRequest;
 import android.view.translation.TranslationResponse;
 import android.view.translation.TranslationSpec;
+import android.view.translation.Translator;
 
 import com.android.internal.os.IResultReceiver;
 
@@ -81,7 +82,10 @@ public abstract class TranslationService extends Service {
      * android.R.styleable#TranslationService translation-service}&gt;</code> tag.
      *
      * <p>Here's an example of how to use it on {@code AndroidManifest.xml}:
-     * TODO: fill in doc example (check CCService/AFService).
+     * <pre> &lt;translation-service
+     *     android:settingsActivity="foo.bar.SettingsActivity"
+     *     . . .
+     * /&gt;</pre>
      */
     public static final String SERVICE_META_DATA = "android.translation_service";
 
@@ -148,7 +152,6 @@ public abstract class TranslationService extends Service {
         void onTranslationSuccess(@NonNull TranslationResponse response);
 
         /**
-         * TODO: implement javadoc
          * @removed use {@link #onTranslationSuccess} with an error response instead.
          */
         @Deprecated
@@ -225,7 +228,7 @@ public abstract class TranslationService extends Service {
      * should call back with {@code false}.</p>
      *
      * @param translationContext the {@link TranslationContext} of the session being created.
-     * @param sessionId the int id of the session.
+     * @param sessionId the id of the session.
      * @param callback {@link Consumer} to notify whether the session was successfully created.
      */
     // TODO(b/176464808): the session id won't be unique cross client/server process. Need to find
@@ -234,8 +237,6 @@ public abstract class TranslationService extends Service {
             int sessionId, @NonNull Consumer<Boolean> callback);
 
     /**
-     * TODO: fill in javadoc.
-     *
      * @removed use {@link #onCreateTranslationSession(TranslationContext, int, Consumer)}
      * instead.
      */
@@ -246,19 +247,16 @@ public abstract class TranslationService extends Service {
     }
 
     /**
-     * TODO: fill in javadoc.
+     * Called when a translation session is finished.
+     *
+     * <p>The translation session is finished when the client calls {@link Translator#destroy()} on
+     * the corresponding translator.
      *
-     * @param sessionId
+     * @param sessionId id of the session that finished.
      */
     public abstract void onFinishTranslationSession(int sessionId);
 
     /**
-     * TODO: fill in javadoc.
-     *
-     * @param request
-     * @param sessionId
-     * @param callback
-     * @param cancellationSignal
      * @removed use
      * {@link #onTranslationRequest(TranslationRequest, int, CancellationSignal, Consumer)} instead.
      */
@@ -276,23 +274,29 @@ public abstract class TranslationService extends Service {
      * {@link TranslationRequest#FLAG_PARTIAL_RESPONSES} was set, the service may call
      * {@code callback.accept()} multiple times with partial responses.</p>
      *
-     * @param request
-     * @param sessionId
-     * @param callback
-     * @param cancellationSignal
+     * @param request The translation request containing the data to be translated.
+     * @param sessionId id of the session that sent the translation request.
+     * @param cancellationSignal A {@link CancellationSignal} that notifies when a client has
+     *                           cancelled the operation in progress.
+     * @param callback {@link Consumer} to pass back the translation response.
      */
     public abstract void onTranslationRequest(@NonNull TranslationRequest request, int sessionId,
             @Nullable CancellationSignal cancellationSignal,
             @NonNull Consumer<TranslationResponse> callback);
 
     /**
-     * TODO: fill in javadoc
+     * Called to request a set of {@link TranslationCapability}s that are supported by the service.
+     *
+     * <p>The set of translation capabilities are limited to those supporting the source and target
+     * {@link TranslationSpec.DataFormat}. e.g. Calling this with
+     * {@link TranslationSpec#DATA_FORMAT_TEXT} as source and target returns only capabilities that
+     * translates text to text.</p>
      *
      * <p>Must call {@code callback.accept} to pass back the set of translation capabilities.</p>
      *
-     * @param sourceFormat
-     * @param targetFormat
-     * @param callback
+     * @param sourceFormat data format restriction of the translation source spec.
+     * @param targetFormat data format restriction of the translation target spec.
+     * @param callback {@link Consumer} to pass back the set of translation capabilities.
      */
     public abstract void onTranslationCapabilitiesRequest(
             @TranslationSpec.DataFormat int sourceFormat,
diff --git a/core/java/android/view/translation/TranslationCapability.java b/core/java/android/view/translation/TranslationCapability.java
index 65b749add1b2..b7e13dda9ff6 100644
--- a/core/java/android/view/translation/TranslationCapability.java
+++ b/core/java/android/view/translation/TranslationCapability.java
@@ -40,15 +40,18 @@ import java.util.function.Consumer;
 public final class TranslationCapability implements Parcelable {
 
     /**
-     * TODO: fill in javadoc
+     * The translation service supports translation between the source and target specs, and it is
+     * ready to be downloaded onto the device.
      */
     public static final @ModelState int STATE_AVAILABLE_TO_DOWNLOAD = 1;
     /**
-     * TODO: fill in javadoc
+     * The translation service supports translation between the source and target specs, and it is
+     * being downloaded onto the device currently.
      */
     public static final @ModelState int STATE_DOWNLOADING = 2;
     /**
-     * TODO: fill in javadoc
+     * The translation service supports translation between the source and target specs, and it is
+     * downloaded and ready to use on device.
      */
     public static final @ModelState int STATE_ON_DEVICE = 3;
     /**
@@ -305,7 +308,7 @@ public final class TranslationCapability implements Parcelable {
     };
 
     @DataClass.Generated(
-            time = 1624307114468L,
+            time = 1629158466039L,
             codegenVersion = "1.0.23",
             sourceFile = "frameworks/base/core/java/android/view/translation/TranslationCapability.java",
             inputSignatures = "public static final @android.view.translation.TranslationCapability.ModelState int STATE_AVAILABLE_TO_DOWNLOAD\npublic static final @android.view.translation.TranslationCapability.ModelState int STATE_DOWNLOADING\npublic static final @android.view.translation.TranslationCapability.ModelState int STATE_ON_DEVICE\npublic static final @android.view.translation.TranslationCapability.ModelState int STATE_NOT_AVAILABLE\npublic static final @android.view.translation.TranslationCapability.ModelState int STATE_REMOVED_AND_AVAILABLE\nprivate final @android.view.translation.TranslationCapability.ModelState int mState\nprivate final @android.annotation.NonNull android.view.translation.TranslationSpec mSourceSpec\nprivate final @android.annotation.NonNull android.view.translation.TranslationSpec mTargetSpec\nprivate final  boolean mUiTranslationEnabled\nprivate final @android.view.translation.TranslationContext.TranslationFlag int mSupportedTranslationFlags\nclass TranslationCapability extends java.lang.Object implements [android.os.Parcelable]\n@com.android.internal.util.DataClass(genHiddenConstDefs=true, genToString=true, genConstructor=false)")
diff --git a/core/java/android/view/translation/TranslationRequest.java b/core/java/android/view/translation/TranslationRequest.java
index df4836ebde46..0d41851ca704 100644
--- a/core/java/android/view/translation/TranslationRequest.java
+++ b/core/java/android/view/translation/TranslationRequest.java
@@ -39,12 +39,16 @@ public final class TranslationRequest implements Parcelable {
     public static final @RequestFlags int FLAG_TRANSLATION_RESULT = 0x1;
     /**
      * Indicates this request wants to receive the dictionary result.
-     * TODO: describe the structure of the result.
+     *
+     * <p>See {@link TranslationResponseValue#EXTRA_DEFINITIONS} for more detail on the structure
+     * of the returned data.
      */
     public static final @RequestFlags int FLAG_DICTIONARY_RESULT = 0x2;
     /**
      * Indicates this request wants to receive the transliteration result.
-     * TODO: describe the structure of the result.
+     *
+     * <p>This returns a CharSequence representation of the transliteration of the translated text.
+     *  See {@link TranslationResponseValue#getTransliteration()}.
      */
     public static final @RequestFlags int FLAG_TRANSLITERATION_RESULT = 0x4;
     /**
@@ -327,7 +331,8 @@ public final class TranslationRequest implements Parcelable {
             return this;
         }
 
-        /** @see #setTranslationRequestValues
+        /**
+         * @see #setTranslationRequestValues
          * @removed
          */
         @DataClass.Generated.Member
@@ -352,7 +357,8 @@ public final class TranslationRequest implements Parcelable {
             return this;
         }
 
-        /** @see #setViewTranslationRequests
+        /**
+         * @see #setViewTranslationRequests
          * @removed
          */
         @DataClass.Generated.Member
@@ -394,7 +400,7 @@ public final class TranslationRequest implements Parcelable {
     }
 
     @DataClass.Generated(
-            time = 1620429997487L,
+            time = 1629159107226L,
             codegenVersion = "1.0.23",
             sourceFile = "frameworks/base/core/java/android/view/translation/TranslationRequest.java",
             inputSignatures = "public static final @android.view.translation.TranslationRequest.RequestFlags int FLAG_TRANSLATION_RESULT\npublic static final @android.view.translation.TranslationRequest.RequestFlags int FLAG_DICTIONARY_RESULT\npublic static final @android.view.translation.TranslationRequest.RequestFlags int FLAG_TRANSLITERATION_RESULT\npublic static final @android.view.translation.TranslationRequest.RequestFlags int FLAG_PARTIAL_RESPONSES\nprivate final @android.view.translation.TranslationRequest.RequestFlags int mFlags\nprivate final @android.annotation.NonNull @com.android.internal.util.DataClass.PluralOf(\"translationRequestValue\") java.util.List<android.view.translation.TranslationRequestValue> mTranslationRequestValues\nprivate final @android.annotation.NonNull @com.android.internal.util.DataClass.PluralOf(\"viewTranslationRequest\") java.util.List<android.view.translation.ViewTranslationRequest> mViewTranslationRequests\nprivate static  int defaultFlags()\nprivate static  java.util.List<android.view.translation.TranslationRequestValue> defaultTranslationRequestValues()\nprivate static  java.util.List<android.view.translation.ViewTranslationRequest> defaultViewTranslationRequests()\nclass TranslationRequest extends java.lang.Object implements [android.os.Parcelable]\npublic abstract @java.lang.Deprecated android.view.translation.TranslationRequest.Builder addTranslationRequestValue(android.view.translation.TranslationRequestValue)\npublic abstract @java.lang.Deprecated android.view.translation.TranslationRequest.Builder addViewTranslationRequest(android.view.translation.ViewTranslationRequest)\nclass BaseBuilder extends java.lang.Object implements []\n@com.android.internal.util.DataClass(genToString=true, genHiddenConstDefs=true, genBuilder=true)\npublic abstract @java.lang.Deprecated android.view.translation.TranslationRequest.Builder addTranslationRequestValue(android.view.translation.TranslationRequestValue)\npublic abstract @java.lang.Deprecated android.view.translation.TranslationRequest.Builder addViewTranslationRequest(android.view.translation.ViewTranslationRequest)\nclass BaseBuilder extends java.lang.Object implements []")
diff --git a/core/java/android/view/translation/TranslationResponseValue.java b/core/java/android/view/translation/TranslationResponseValue.java
index a24dbc3ae4f8..9dff2d56322b 100644
--- a/core/java/android/view/translation/TranslationResponseValue.java
+++ b/core/java/android/view/translation/TranslationResponseValue.java
@@ -93,9 +93,11 @@ public final class TranslationResponseValue implements Parcelable {
     @NonNull
     private final Bundle mExtras;
 
+    // TODO: Add example of transliteration.
     /**
      * The transliteration result of the translated text.
-     * TODO: Describe the result structure.
+     *
+     * <p>This returns a CharSequence representation of the transliteration of the translated text.
      */
     @Nullable
     private final CharSequence mTransliteration;
@@ -223,7 +225,8 @@ public final class TranslationResponseValue implements Parcelable {
 
     /**
      * The transliteration result of the translated text.
-     * TODO: Describe the result structure.
+     *
+     * <p>This returns a CharSequence representation of the transliteration of the translated text.
      */
     @DataClass.Generated.Member
     public @Nullable CharSequence getTransliteration() {
@@ -407,7 +410,8 @@ public final class TranslationResponseValue implements Parcelable {
 
         /**
          * The transliteration result of the translated text.
-         * TODO: Describe the result structure.
+         *
+         * <p>This returns a CharSequence representation of the transliteration of the translated text.
          */
         @DataClass.Generated.Member
         public @NonNull Builder setTransliteration(@NonNull CharSequence value) {
@@ -448,7 +452,7 @@ public final class TranslationResponseValue implements Parcelable {
     }
 
     @DataClass.Generated(
-            time = 1622133051937L,
+            time = 1631057245846L,
             codegenVersion = "1.0.23",
             sourceFile = "frameworks/base/core/java/android/view/translation/TranslationResponseValue.java",
             inputSignatures = "public static final  int STATUS_SUCCESS\npublic static final  int STATUS_ERROR\npublic static final  java.lang.String EXTRA_DEFINITIONS\nprivate final @android.view.translation.TranslationResponseValue.Status int mStatusCode\nprivate final @android.annotation.Nullable java.lang.CharSequence mText\nprivate final @android.annotation.NonNull android.os.Bundle mExtras\nprivate final @android.annotation.Nullable java.lang.CharSequence mTransliteration\npublic static @android.annotation.NonNull android.view.translation.TranslationResponseValue forError()\nprivate static  java.lang.CharSequence defaultText()\nprivate static  android.os.Bundle defaultExtras()\nprivate  boolean extrasEquals(android.os.Bundle)\nprivate static  java.lang.CharSequence defaultTransliteration()\nclass TranslationResponseValue extends java.lang.Object implements [android.os.Parcelable]\nclass BaseBuilder extends java.lang.Object implements []\n@com.android.internal.util.DataClass(genBuilder=true, genToString=true, genEqualsHashCode=true, genHiddenConstDefs=true)\nclass BaseBuilder extends java.lang.Object implements []")